Kenji Arai / mbed-os_TYBLE16

mbed-os5 only for TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

rtos/Mutex.h@1:9db0e321a9f4, 2019-12-31 (annotated)

Committer:
kenjiArai
Date:
Tue Dec 31 06:02:27 2019 +0000
Revision:
1:9db0e321a9f4
Parent:
0:5b88d5760320 
updated based on mbed-os5.15.0

Who changed what in which revision?

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