Daniel Vilela / Mutex

cxcsss

Dependents:   I2C

Mutex.h@0:03d26b5ff6db, 2019-11-27 (annotated)

Committer:
daniwestside
Date:
Wed Nov 27 11:11:09 2019 +0000
Revision:
0:03d26b5ff6db
xx

Who changed what in which revision?

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