Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
Mutex.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2012 ARM Limited
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to deal
6  * in the Software without restriction, including without limitation the rights
7  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8  * copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20  * SOFTWARE.
21  */
22 #ifndef MUTEX_H
23 #define MUTEX_H
24 
25 #include <stdint.h>
26 #include "cmsis_os2.h"
27 #include "mbed_rtos1_types.h"
28 #include "mbed_rtos_storage.h"
29 
30 #include "platform/NonCopyable.h"
31 #include "platform/ScopedLock.h"
32 #include "platform/mbed_toolchain.h"
33 
34 namespace rtos {
35 /** \addtogroup rtos */
36 /** @{*/
37 
38 class Mutex;
39 /** Typedef for the mutex lock
40  *
41  * Usage:
42  * @code
43  * void foo(Mutex &m) {
44  * ScopedMutexLock lock(m);
45  * // Mutex lock protects code in this block
46  * }
47  * @endcode
48  */
49 typedef mbed::ScopedLock<Mutex> ScopedMutexLock;
50 
51 /**
52  * \defgroup rtos_Mutex Mutex class
53  * @{
54  */
55 
56 /** The Mutex class is used to synchronize the execution of threads.
57  This is, for example, used to protect access to a shared resource.
58 
59  @note You cannot use member functions of this class in ISR context. If you require Mutex functionality within
60  ISR handler, consider using @a Semaphore.
61 
62  @note
63  Memory considerations: The mutex control structures are created on the current thread's stack, both for the Mbed OS
64  and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
65 */
66 class Mutex : private mbed::NonCopyable<Mutex> {
67 public:
68  /** Create and Initialize a Mutex object
69  *
70  * @note You cannot call this function from ISR context.
71  */
72  Mutex();
73 
74  /** Create and Initialize a Mutex object
75 
76  @param name name to be used for this mutex. It has to stay allocated for the lifetime of the thread.
77  @note You cannot call this function from ISR context.
78  */
79  Mutex(const char *name);
80 
81  /**
82  Wait until a Mutex becomes available.
83 
84  @return status code that indicates the execution status of the function:
85  @a osOK the mutex has been obtained.
86 
87  @note You cannot call this function from ISR context.
88  @note This function treats RTOS errors as fatal system errors, so it can only return osOK.
89  Use of the return value is deprecated, as the return is expected to become void in the future.
90  */
91  osStatus lock(void);
92 
93  /**
94  Wait until a Mutex becomes available.
95 
96  @deprecated Do not use this function. This function has been replaced with lock(), trylock() and trylock_for() functions.
97 
98  @param millisec timeout value.
99  @return status code that indicates the execution status of the function:
100  @a osOK the mutex has been obtained.
101  @a osErrorTimeout the mutex could not be obtained in the given time.
102  @a osErrorResource the mutex could not be obtained when no timeout was specified.
103 
104  @note You cannot call this function from ISR context.
105  @note This function treats RTOS errors as fatal system errors, so it can only return osOK or
106  osErrorResource in case when millisec is 0 or osErrorTimeout if millisec is not osWaitForever.
107  */
108  MBED_DEPRECATED_SINCE("mbed-os-5.10.0", "Replaced with lock(), trylock() and trylock_for() functions")
109  osStatus lock(uint32_t millisec);
110 
111  /** Try to lock the mutex, and return immediately
112  @return true if the mutex was acquired, false otherwise.
113  @note equivalent to trylock_for(0)
114 
115  @note You cannot call this function from ISR context.
116  */
117  bool trylock();
118 
119  /** Try to lock the mutex for a specified time
120  @param millisec timeout value.
121  @return true if the mutex was acquired, false otherwise.
122  @note the underlying RTOS may have a limit to the maximum wait time
123  due to internal 32-bit computations, but this is guaranteed to work if the
124  wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
125  the lock attempt will time out earlier than specified.
126 
127  @note You cannot call this function from ISR context.
128  */
129  bool trylock_for(uint32_t millisec);
130 
131  /** Try to lock the mutex until specified time
132  @param millisec absolute timeout time, referenced to Kernel::get_ms_count()
133  @return true if the mutex was acquired, false otherwise.
134  @note the underlying RTOS may have a limit to the maximum wait time
135  due to internal 32-bit computations, but this is guaranteed to work if the
136  wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
137  the lock attempt will time out earlier than specified.
138 
139  @note You cannot call this function from ISR context.
140  */
141  bool trylock_until(uint64_t millisec);
142 
143  /**
144  Unlock the mutex that has previously been locked by the same thread
145 
146  @return status code that indicates the execution status of the function:
147  @a osOK the mutex has been released.
148 
149  @note You cannot call this function from ISR context.
150  @note This function treats RTOS errors as fatal system errors, so it can only return osOK.
151  Use of the return value is deprecated, as the return is expected to become void in the future.
152  */
153  osStatus unlock();
154 
155  /** Get the owner the this mutex
156  @return the current owner of this mutex.
157 
158  @note You cannot call this function from ISR context.
159  */
160  osThreadId get_owner();
161 
162  /** Mutex destructor
163  *
164  * @note You cannot call this function from ISR context.
165  */
166  ~Mutex();
167 
168 private:
169  void constructor(const char *name = NULL);
170  friend class ConditionVariable;
171 
172  osMutexId_t _id;
173  mbed_rtos_storage_mutex_t _obj_mem;
174  uint32_t _count;
175 };
176 /** @}*/
177 /** @}*/
178 }
179 #endif
180 
181 
mbed::ScopedLock
RAII-style mechanism for owning a lock of Lockable object for the duration of a scoped block...
Definition: ScopedLock.h:62
rtos::Mutex::Mutex
Mutex()
Create and Initialize a Mutex object.
rtos::Mutex::trylock_for
bool trylock_for(uint32_t millisec)
Try to lock the mutex for a specified time.
rtos::Mutex::lock
osStatus lock(void)
Wait until a Mutex becomes available.
mbed_rtos_storage_mutex_t
osRtxMutex_t mbed_rtos_storage_mutex_t
RTOS primitives storage types for RTX.
Definition: mbed_rtos_storage.h:46
mbed::NonCopyable
Prevents generation of copy constructor and copy assignment operator in derived classes.
Definition: NonCopyable.h:168
rtos::Mutex::~Mutex
~Mutex()
Mutex destructor.
rtos::ScopedMutexLock
mbed::ScopedLock< Mutex > ScopedMutexLock
Typedef for the mutex lock.
Definition: Mutex.h:38
rtos::Mutex::trylock_until
bool trylock_until(uint64_t millisec)
Try to lock the mutex until specified time.
rtos::Mutex::unlock
osStatus unlock()
Unlock the mutex that has previously been locked by the same thread.
rtos::Mutex
The Mutex class is used to synchronize the execution of threads.
Definition: Mutex.h:66
rtos::ConditionVariable
The ConditionVariable class is a synchronization primitive that allows threads to wait until a partic...
Definition: ConditionVariable.h:152
rtos::Mutex::trylock
bool trylock()
Try to lock the mutex, and return immediately.
rtos::Mutex::get_owner
osThreadId get_owner()
Get the owner the this mutex.
MBED_DEPRECATED_SINCE
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
Definition: mbed_toolchain.h:379
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.