Mutex.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2019 ARM Limited
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy
00005  * of this software and associated documentation files (the "Software"), to deal
00006  * in the Software without restriction, including without limitation the rights
00007  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008  * copies of the Software, and to permit persons to whom the Software is
00009  * furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included in
00012  * all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00020  * SOFTWARE.
00021  */
00022 #ifndef MUTEX_H
00023 #define MUTEX_H
00024 
00025 #include <stdint.h>
00026 #include "rtos/mbed_rtos_types.h"
00027 #include "rtos/mbed_rtos1_types.h"
00028 #include "rtos/mbed_rtos_storage.h"
00029 
00030 #include "platform/NonCopyable.h"
00031 #include "platform/ScopedLock.h"
00032 #include "platform/mbed_toolchain.h"
00033 
00034 namespace rtos {
00035 /** \addtogroup rtos-public-api */
00036 /** @{*/
00037 
00038 class Mutex;
00039 /** Typedef for the mutex lock
00040  *
00041  * Usage:
00042  * @code
00043  * void foo(Mutex &m) {
00044  *     ScopedMutexLock lock(m);
00045  *     // Mutex lock protects code in this block
00046  * }
00047  * @endcode
00048  */
00049 typedef mbed::ScopedLock<Mutex> ScopedMutexLock;
00050 
00051 /**
00052  * \defgroup rtos_Mutex Mutex class
00053  * @{
00054  */
00055 
00056 /** The Mutex class is used to synchronize the execution of threads.
00057  This is, for example, used to protect access to a shared resource.
00058 
00059  In bare-metal builds, the Mutex class is a dummy, so lock() and unlock() are no-ops.
00060 
00061  @note You cannot use member functions of this class in ISR context. If you require Mutex functionality within
00062  ISR handler, consider using @a Semaphore.
00063 
00064  @note
00065  Memory considerations: The mutex control structures are created on the current thread's stack, both for the Mbed OS
00066  and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
00067 */
00068 class Mutex : private mbed::NonCopyable<Mutex> {
00069 public:
00070     /** Create and Initialize a Mutex object
00071      *
00072      * @note You cannot call this function from ISR context.
00073     */
00074     Mutex();
00075 
00076     /** Create and Initialize a Mutex object
00077 
00078      @param name name to be used for this mutex. It has to stay allocated for the lifetime of the thread.
00079      @note You cannot call this function from ISR context.
00080     */
00081     Mutex(const char *name);
00082 
00083     /**
00084       Wait until a Mutex becomes available.
00085 
00086       @return  status code that indicates the execution status of the function:
00087                @a osOK the mutex has been obtained.
00088 
00089       @note You cannot call this function from ISR context.
00090       @note This function treats RTOS errors as fatal system errors, so it can only return osOK.
00091             Use of the return value is deprecated, as the return is expected to become void in the future.
00092      */
00093 #if MBED_CONF_RTOS_PRESENT
00094     osStatus lock();
00095 #else
00096     void lock(); // Value return backwards compatibility not required for non-RTOS
00097 #endif
00098 
00099     /**
00100       Wait until a Mutex becomes available.
00101 
00102       @deprecated Do not use this function. This function has been replaced with lock(), trylock() and trylock_for() functions.
00103 
00104       @param   millisec  timeout value.
00105       @return  status code that indicates the execution status of the function:
00106                @a osOK the mutex has been obtained.
00107                @a osErrorTimeout the mutex could not be obtained in the given time.
00108                @a osErrorResource the mutex could not be obtained when no timeout was specified.
00109 
00110       @note You cannot call this function from ISR context.
00111       @note This function treats RTOS errors as fatal system errors, so it can only return osOK or
00112             osErrorResource in case when millisec is 0 or osErrorTimeout if millisec is not osWaitForever.
00113      */
00114     MBED_DEPRECATED_SINCE("mbed-os-5.10.0", "Replaced with lock(), trylock() and trylock_for() functions")
00115     osStatus lock(uint32_t millisec);
00116 
00117     /** Try to lock the mutex, and return immediately
00118       @return true if the mutex was acquired, false otherwise.
00119       @note equivalent to trylock_for(0)
00120 
00121       @note You cannot call this function from ISR context.
00122      */
00123     bool trylock();
00124 
00125     /** Try to lock the mutex for a specified time
00126       @param   millisec  timeout value.
00127       @return true if the mutex was acquired, false otherwise.
00128       @note the underlying RTOS may have a limit to the maximum wait time
00129             due to internal 32-bit computations, but this is guaranteed to work if the
00130             wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
00131             the lock attempt will time out earlier than specified.
00132 
00133       @note You cannot call this function from ISR context.
00134      */
00135     bool trylock_for(uint32_t millisec);
00136 
00137     /** Try to lock the mutex until specified time
00138       @param   millisec  absolute timeout time, referenced to Kernel::get_ms_count()
00139       @return true if the mutex was acquired, false otherwise.
00140       @note the underlying RTOS may have a limit to the maximum wait time
00141             due to internal 32-bit computations, but this is guaranteed to work if the
00142             wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
00143             the lock attempt will time out earlier than specified.
00144 
00145       @note You cannot call this function from ISR context.
00146      */
00147     bool trylock_until(uint64_t millisec);
00148 
00149     /**
00150       Unlock the mutex that has previously been locked by the same thread
00151 
00152       @return status code that indicates the execution status of the function:
00153               @a osOK the mutex has been released.
00154 
00155       @note You cannot call this function from ISR context.
00156       @note This function treats RTOS errors as fatal system errors, so it can only return osOK.
00157             Use of the return value is deprecated, as the return is expected to become void in the future.
00158      */
00159 #if MBED_CONF_RTOS_PRESENT
00160     osStatus unlock();
00161 #else
00162     void unlock(); // Value return backwards compatibility not required for non-RTOS
00163 #endif
00164 
00165     /** Get the owner the this mutex
00166       @return  the current owner of this mutex.
00167 
00168       @note You cannot call this function from ISR context.
00169      */
00170     osThreadId_t get_owner();
00171 
00172     /** Mutex destructor
00173      *
00174      * @note You cannot call this function from ISR context.
00175      */
00176     ~Mutex();
00177 
00178 private:
00179 #if MBED_CONF_RTOS_PRESENT
00180     void constructor(const char *name = nullptr);
00181     friend class ConditionVariable;
00182 
00183     osMutexId_t               _id;
00184     mbed_rtos_storage_mutex_t _obj_mem;
00185     uint32_t                  _count;
00186 #endif
00187 };
00188 
00189 #if !MBED_CONF_RTOS_PRESENT
00190 inline Mutex::Mutex()
00191 {
00192 }
00193 
00194 inline Mutex::Mutex(const char *)
00195 {
00196 }
00197 
00198 inline Mutex::~Mutex()
00199 {
00200 }
00201 
00202 inline void Mutex::lock()
00203 {
00204 }
00205 
00206 inline bool Mutex::trylock()
00207 {
00208     return true;
00209 }
00210 
00211 inline bool Mutex::trylock_for(uint32_t)
00212 {
00213     return true;
00214 }
00215 
00216 inline bool Mutex::trylock_until(uint64_t)
00217 {
00218     return true;
00219 }
00220 
00221 inline void Mutex::unlock()
00222 {
00223 }
00224 #endif
00225 
00226 /** @}*/
00227 /** @}*/
00228 }
00229 #endif