Mutex.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2012 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 "cmsis_os2.h"
00027 #include "mbed_rtos1_types.h"
00028 #include "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 */
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  @note You cannot use member functions of this class in ISR context. If you require Mutex functionality within
00060  ISR handler, consider using @a Semaphore.
00061 
00062  @note
00063  Memory considerations: The mutex control structures will be created on current thread's stack, both for the Mbed OS
00064  and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
00065 */
00066 class Mutex : private mbed::NonCopyable<Mutex> {
00067 public:
00068     /** Create and Initialize a Mutex object
00069      *
00070      * @note You cannot call this function from ISR context.
00071     */
00072     Mutex();
00073 
00074     /** Create and Initialize a Mutex object
00075 
00076      @param name name to be used for this mutex. It has to stay allocated for the lifetime of the thread.
00077      @note You cannot call this function from ISR context.
00078     */
00079     Mutex(const char *name);
00080 
00081     /**
00082       Wait until a Mutex becomes available.
00083 
00084       @return  status code that indicates the execution status of the function:
00085                @a osOK the mutex has been obtained.
00086 
00087       @note You cannot call this function from ISR context.
00088       @note This function treats RTOS errors as fatal system errors, so can only return osOK.
00089             Use of the return value is deprecated, as the return is expected to become void in the future.
00090      */
00091     osStatus lock(void);
00092 
00093     /**
00094       For backwards compatibility.
00095       @deprecated Do not use this function. This function has been replaced with lock(), trylock() and trylock_for() functions.
00096 
00097       Wait until a Mutex becomes available.
00098       @param   millisec  timeout value or 0 in case of no time-out.
00099       @return  status code that indicates the execution status of the function:
00100                @a osOK the mutex has been obtained.
00101                @a osErrorTimeout the mutex could not be obtained in the given time.
00102                @a osErrorResource the mutex could not be obtained when no timeout was specified.
00103 
00104       @note You cannot call this function from ISR context.
00105       @note This function treats RTOS errors as fatal system errors, so can only return osOK or
00106             osErrorResource in case when millisec is 0 or osErrorTimeout if millisec is not osWaitForever.
00107      */
00108     MBED_DEPRECATED_SINCE("mbed-os-5.10.0", "Replaced with lock(), trylock() and trylock_for() functions")
00109     osStatus lock(uint32_t millisec);
00110 
00111     /** Try to lock the mutex, and return immediately
00112       @return true if the mutex was acquired, false otherwise.
00113       @note equivalent to trylock_for(0)
00114 
00115       @note You cannot call this function from ISR context.
00116      */
00117     bool trylock();
00118 
00119     /** Try to lock the mutex for a specified time
00120       @param   millisec  timeout value or 0 in case of no time-out.
00121       @return true if the mutex was acquired, false otherwise.
00122       @note the underlying RTOS may have a limit to the maximum wait time
00123             due to internal 32-bit computations, but this is guaranteed to work if the
00124             wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
00125             the lock attempt will time out earlier than specified.
00126 
00127       @note You cannot call this function from ISR context.
00128      */
00129     bool trylock_for(uint32_t millisec);
00130 
00131     /** Try to lock the mutex until specified time
00132       @param   millisec  absolute timeout time, referenced to Kernel::get_ms_count()
00133       @return true if the mutex was acquired, false otherwise.
00134       @note the underlying RTOS may have a limit to the maximum wait time
00135             due to internal 32-bit computations, but this is guaranteed to work if the
00136             wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
00137             the lock attempt will time out earlier than specified.
00138 
00139       @note You cannot call this function from ISR context.
00140      */
00141     bool trylock_until(uint64_t millisec);
00142 
00143     /**
00144       Unlock the mutex that has previously been locked by the same thread
00145 
00146       @return status code that indicates the execution status of the function:
00147               @a osOK the mutex has been released.
00148 
00149       @note You cannot call this function from ISR context.
00150       @note This function treats RTOS errors as fatal system errors, so can only return osOK.
00151             Use of the return value is deprecated, as the return is expected to become void in the future.
00152      */
00153     osStatus unlock();
00154 
00155     /** Get the owner the this mutex
00156       @return  the current owner of this mutex.
00157 
00158       @note You cannot call this function from ISR context.
00159      */
00160     osThreadId get_owner();
00161 
00162     /** Mutex destructor
00163      *
00164      * @note You cannot call this function from ISR context.
00165      */
00166     ~Mutex();
00167 
00168 private:
00169     void constructor(const char *name = NULL);
00170     friend class ConditionVariable;
00171 
00172     osMutexId_t               _id;
00173     mbed_rtos_storage_mutex_t _obj_mem;
00174     uint32_t                  _count;
00175 };
00176 /** @}*/
00177 /** @}*/
00178 }
00179 #endif
00180 
00181