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 
00033 namespace rtos {
00034 /** \addtogroup rtos */
00035 /** @{*/
00036 
00037 class Mutex;
00038 /** Typedef for the mutex lock
00039  *
00040  * Usage:
00041  * @code
00042  * void foo(Mutex &m) {
00043  *     ScopedMutexLock lock(m);
00044  *     // Mutex lock protects code in this block
00045  * }
00046  * @endcode
00047  */
00048 typedef mbed::ScopedLock<Mutex> ScopedMutexLock;
00049 
00050 /**
00051  * \defgroup rtos_Mutex Mutex class
00052  * @{
00053  */
00054  
00055 /** The Mutex class is used to synchronize the execution of threads.
00056  This is for example used to protect access to a shared resource.
00057 
00058  @note You cannot use member functions of this class in ISR context. If you require Mutex functionality within
00059  ISR handler, consider using @a Semaphore.
00060 
00061  @note
00062  Memory considerations: The mutex control structures will be created on current thread's stack, both for the Mbed OS
00063  and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
00064 */
00065 class Mutex : private mbed::NonCopyable<Mutex> {
00066 public:
00067     /** Create and Initialize a Mutex object
00068      *
00069      * @note You cannot call this function from ISR context.
00070     */
00071     Mutex();
00072 
00073     /** Create and Initialize a Mutex object
00074 
00075      @param name name to be used for this mutex. It has to stay allocated for the lifetime of the thread.
00076 
00077      @note You cannot call this function from ISR context.
00078     */
00079     Mutex(const char *name);
00080 
00081     /** Wait until a Mutex becomes available.
00082       @param   millisec  timeout value or 0 in case of no time-out. (default: osWaitForever)
00083       @return  status code that indicates the execution status of the function:
00084                @a osOK the mutex has been obtained.
00085                @a osErrorTimeout the mutex could not be obtained in the given time.
00086                @a osErrorParameter internal error.
00087                @a osErrorResource the mutex could not be obtained when no timeout was specified.
00088                @a osErrorISR this function cannot be called from the interrupt service routine.
00089 
00090       @note You cannot call this function from ISR context.
00091      */
00092     osStatus lock(uint32_t millisec=osWaitForever);
00093 
00094     /** Try to lock the mutex, and return immediately
00095       @return true if the mutex was acquired, false otherwise.
00096       @note equivalent to trylock_for(0)
00097 
00098       @note You cannot call this function from ISR context.
00099      */
00100     bool trylock();
00101 
00102     /** Try to lock the mutex for a specified time
00103       @param   millisec  timeout value or 0 in case of no time-out.
00104       @return true if the mutex was acquired, false otherwise.
00105       @note the underlying RTOS may have a limit to the maximum wait time
00106             due to internal 32-bit computations, but this is guaranteed to work if the
00107             wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
00108             the lock attempt will time out earlier than specified.
00109 
00110       @note You cannot call this function from ISR context.
00111      */
00112     bool trylock_for(uint32_t millisec);
00113 
00114     /** Try to lock the mutex until specified time
00115       @param   millisec  absolute timeout time, referenced to Kernel::get_ms_count()
00116       @return true if the mutex was acquired, false otherwise.
00117       @note the underlying RTOS may have a limit to the maximum wait time
00118             due to internal 32-bit computations, but this is guaranteed to work if the
00119             wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
00120             the lock attempt will time out earlier than specified.
00121 
00122       @note You cannot call this function from ISR context.
00123      */
00124     bool trylock_until(uint64_t millisec);
00125 
00126     /** Unlock the mutex that has previously been locked by the same thread
00127       @return status code that indicates the execution status of the function:
00128               @a osOK the mutex has been released.
00129               @a osErrorParameter internal error.
00130               @a osErrorResource the mutex was not locked or the current thread wasn't the owner.
00131               @a osErrorISR this function cannot be called from the interrupt service routine.
00132 
00133       @note You cannot call this function from ISR context.
00134      */
00135     osStatus unlock();
00136 
00137     /** Get the owner the this mutex
00138       @return  the current owner of this mutex.
00139 
00140       @note You cannot call this function from ISR context.
00141      */
00142     osThreadId get_owner();
00143 
00144     /** Mutex destructor
00145      *
00146      * @note You cannot call this function from ISR context.
00147      */
00148     ~Mutex();
00149 
00150 private:
00151     void constructor(const char *name = NULL);
00152     friend class ConditionVariable;
00153 
00154     osMutexId_t               _id;
00155     mbed_rtos_storage_mutex_t _obj_mem;
00156     uint32_t                  _count;
00157 };
00158 /** @}*/
00159 /** @}*/
00160 }
00161 #endif
00162 
00163