Mistake on this page?
Report an issue in GitHub or email us
Mutex.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2019 ARM Limited
3  * SPDX-License-Identifier: MIT
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a copy
6  * of this software and associated documentation files (the "Software"), to deal
7  * in the Software without restriction, including without limitation the rights
8  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9  * copies of the Software, and to permit persons to whom the Software is
10  * furnished to do so, subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in
13  * all copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21  * SOFTWARE.
22  */
23 #ifndef MUTEX_H
24 #define MUTEX_H
25 
26 #include <stdint.h>
27 #include "rtos/mbed_rtos_types.h"
28 #include "rtos/internal/mbed_rtos1_types.h"
29 #include "rtos/internal/mbed_rtos_storage.h"
30 #include "rtos/Kernel.h"
31 
32 #include "platform/NonCopyable.h"
33 #include "platform/ScopedLock.h"
34 #include "platform/mbed_toolchain.h"
35 
36 namespace rtos {
37 /** \addtogroup rtos-public-api */
38 /** @{*/
39 
40 class Mutex;
41 /** Typedef for the mutex lock
42  *
43  * Usage:
44  * @code
45  * void foo(Mutex &m) {
46  * ScopedMutexLock lock(m);
47  * // Mutex lock protects code in this block
48  * }
49  * @endcode
50  */
52 
53 /**
54  * \defgroup rtos_Mutex Mutex class
55  * @{
56  */
57 
58 /** The Mutex class is used to synchronize the execution of threads.
59  This is, for example, used to protect access to a shared resource.
60 
61  In bare-metal builds, the Mutex class is a dummy, so lock() and unlock() are no-ops.
62 
63  @note You cannot use member functions of this class in ISR context. If you require Mutex functionality within
64  ISR handler, consider using @a Semaphore.
65 
66  @note
67  Memory considerations: The mutex control structures are created on the current thread's stack, both for the Mbed OS
68  and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
69 */
70 class Mutex : private mbed::NonCopyable<Mutex> {
71 public:
72  /** Create and Initialize a Mutex object
73  *
74  * @note You cannot call this function from ISR context.
75  */
76  Mutex();
77 
78  /** Create and Initialize a Mutex object
79 
80  @param name name to be used for this mutex. It has to stay allocated for the lifetime of the thread.
81  @note You cannot call this function from ISR context.
82  */
83  Mutex(const char *name);
84 
85  /**
86  Wait until a Mutex becomes available.
87 
88  @note You cannot call this function from ISR context.
89  */
90  void lock();
91 
92  /** Try to lock the mutex, and return immediately
93  @return true if the mutex was acquired, false otherwise.
94  @note equivalent to trylock_for(0)
95 
96  @note You cannot call this function from ISR context.
97  */
98  bool trylock();
99 
100  /** Try to lock the mutex for a specified time
101  @param millisec timeout value.
102  @return true if the mutex was acquired, false otherwise.
103  @note the underlying RTOS may have a limit to the maximum wait time
104  due to internal 32-bit computations, but this is guaranteed to work if the
105  wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
106  the lock attempt will time out earlier than specified.
107 
108  @note You cannot call this function from ISR context.
109  @deprecated Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.
110  */
111  MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.")
112  bool trylock_for(uint32_t millisec);
113 
114  /** Try to lock the mutex for a specified time
115  @param rel_time timeout value.
116  @return true if the mutex was acquired, false otherwise.
117  @note the underlying RTOS may have a limit to the maximum wait time
118  due to internal 32-bit computations, but this is guaranteed to work if the
119  wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
120  the lock attempt will time out earlier than specified.
121 
122  @note You cannot call this function from ISR context.
123  */
124  bool trylock_for(Kernel::Clock::duration_u32 rel_time);
125 
126  /** Try to lock the mutex until specified time
127  @param millisec absolute timeout time, referenced to Kernel::get_ms_count()
128  @return true if the mutex was acquired, false otherwise.
129  @note the underlying RTOS may have a limit to the maximum wait time
130  due to internal 32-bit computations, but this is guaranteed to work if the
131  wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
132  the lock attempt will time out earlier than specified.
133 
134  @note You cannot call this function from ISR context.
135  @deprecated Pass a chrono time_point, not an integer millisecond count. For example use
136  `Kernel::Clock::now() + 5s` rather than `Kernel::get_ms_count() + 5000`.
137  */
138  MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono time_point, not an integer millisecond count. For example use `Kernel::Clock::now() + 5s` rather than `Kernel::get_ms_count() + 5000`.")
139  bool trylock_until(uint64_t millisec);
140 
141  /** Try to lock the mutex until specified time
142  @param abs_time absolute timeout time, referenced to Kernel::Clock
143  @return true if the mutex was acquired, false otherwise.
144  @note the underlying RTOS may have a limit to the maximum wait time
145  due to internal 32-bit computations, but this is guaranteed to work if the
146  wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
147  the lock attempt will time out earlier than specified.
148 
149  @note You cannot call this function from ISR context.
150  */
151  bool trylock_until(Kernel::Clock::time_point abs_time);
152 
153  /**
154  Unlock the mutex that has previously been locked by the same thread
155 
156  @note You cannot call this function from ISR context.
157  */
158  void unlock();
159 
160  /** Get the owner the this mutex
161  @return the current owner of this mutex.
162 
163  @note You cannot call this function from ISR context.
164  */
165  osThreadId_t get_owner();
166 
167  /** Mutex destructor
168  *
169  * @note You cannot call this function from ISR context.
170  */
171  ~Mutex();
172 
173 private:
174 #if MBED_CONF_RTOS_PRESENT
175  void constructor(const char *name = nullptr);
176  friend class ConditionVariable;
177 
178  osMutexId_t _id;
179  mbed_rtos_storage_mutex_t _obj_mem;
180  uint32_t _count;
181 #endif
182 };
183 
184 #if !MBED_CONF_RTOS_PRESENT
185 inline Mutex::Mutex()
186 {
187 }
188 
189 inline Mutex::Mutex(const char *)
190 {
191 }
192 
194 {
195 }
196 
197 inline void Mutex::lock()
198 {
199 }
200 
201 inline bool Mutex::trylock()
202 {
203  return true;
204 }
205 
206 inline bool Mutex::trylock_for(uint32_t)
207 {
208  return true;
209 }
210 
211 inline bool Mutex::trylock_for(Kernel::Clock::duration_u32)
212 {
213  return true;
214 }
215 
216 inline bool Mutex::trylock_until(uint64_t)
217 {
218  return true;
219 }
220 
221 inline bool Mutex::trylock_until(Kernel::Clock::time_point)
222 {
223  return true;
224 }
225 
226 inline void Mutex::unlock()
227 {
228 }
229 #endif
230 
231 /** @}*/
232 /** @}*/
233 }
234 #endif
RAII-style mechanism for owning a lock of Lockable object for the duration of a scoped block...
Definition: ScopedLock.h:63
bool trylock()
Try to lock the mutex, and return immediately.
Definition: Mutex.h:201
~Mutex()
Mutex destructor.
Definition: Mutex.h:193
Prevents generation of copy constructor and copy assignment operator in derived classes.
Definition: NonCopyable.h:162
Mutex()
Create and Initialize a Mutex object.
Definition: Mutex.h:185
void unlock()
Unlock the mutex that has previously been locked by the same thread.
Definition: Mutex.h:226
osThreadId_t get_owner()
Get the owner the this mutex.
bool trylock_for(uint32_t millisec)
Try to lock the mutex for a specified time.
Definition: Mutex.h:206
bool trylock_until(uint64_t millisec)
Try to lock the mutex until specified time.
Definition: Mutex.h:216
The Mutex class is used to synchronize the execution of threads.
Definition: Mutex.h:70
The ConditionVariable class is a synchronization primitive that allows threads to wait until a partic...
void lock()
Wait until a Mutex becomes available.
Definition: Mutex.h:197
mbed::ScopedLock< Mutex > ScopedMutexLock
Typedef for the mutex lock.
Definition: Mutex.h:40
Definition: TaskBase.h:25
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
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.