BA / SerialCom

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of OmniWheels by Gustav Atmel

mbed-os/rtos/Mutex.h@2:798925c9e4a8, 2018-05-01 (annotated)

Committer:
gustavatmel
Date:
Tue May 01 15:55:34 2018 +0000
Revision:
2:798925c9e4a8
Parent:
1:9c5af431a1f1 
bluetooth

Who changed what in which revision?

UserRevisionLine numberNew contents of line
gustavatmel 1:9c5af431a1f1 1 /* mbed Microcontroller Library
gustavatmel 1:9c5af431a1f1 2 * Copyright (c) 2006-2012 ARM Limited
gustavatmel 1:9c5af431a1f1 3 *
gustavatmel 1:9c5af431a1f1 4 * Permission is hereby granted, free of charge, to any person obtaining a copy
gustavatmel 1:9c5af431a1f1 5 * of this software and associated documentation files (the "Software"), to deal
gustavatmel 1:9c5af431a1f1 6 * in the Software without restriction, including without limitation the rights
gustavatmel 1:9c5af431a1f1 7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
gustavatmel 1:9c5af431a1f1 8 * copies of the Software, and to permit persons to whom the Software is
gustavatmel 1:9c5af431a1f1 9 * furnished to do so, subject to the following conditions:
gustavatmel 1:9c5af431a1f1 10 *
gustavatmel 1:9c5af431a1f1 11 * The above copyright notice and this permission notice shall be included in
gustavatmel 1:9c5af431a1f1 12 * all copies or substantial portions of the Software.
gustavatmel 1:9c5af431a1f1 13 *
gustavatmel 1:9c5af431a1f1 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
gustavatmel 1:9c5af431a1f1 15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
gustavatmel 1:9c5af431a1f1 16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
gustavatmel 1:9c5af431a1f1 17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
gustavatmel 1:9c5af431a1f1 18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
gustavatmel 1:9c5af431a1f1 19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
gustavatmel 1:9c5af431a1f1 20 * SOFTWARE.
gustavatmel 1:9c5af431a1f1 21 */
gustavatmel 1:9c5af431a1f1 22 #ifndef MUTEX_H
gustavatmel 1:9c5af431a1f1 23 #define MUTEX_H
gustavatmel 1:9c5af431a1f1 24
gustavatmel 1:9c5af431a1f1 25 #include <stdint.h>
gustavatmel 1:9c5af431a1f1 26 #include "cmsis_os2.h"
gustavatmel 1:9c5af431a1f1 27 #include "mbed_rtos1_types.h"
gustavatmel 1:9c5af431a1f1 28 #include "mbed_rtos_storage.h"
gustavatmel 1:9c5af431a1f1 29
gustavatmel 1:9c5af431a1f1 30 #include "platform/NonCopyable.h"
gustavatmel 1:9c5af431a1f1 31 #include "platform/ScopedLock.h"
gustavatmel 1:9c5af431a1f1 32
gustavatmel 1:9c5af431a1f1 33 namespace rtos {
gustavatmel 1:9c5af431a1f1 34 /** \addtogroup rtos */
gustavatmel 1:9c5af431a1f1 35 /** @{*/
gustavatmel 1:9c5af431a1f1 36
gustavatmel 1:9c5af431a1f1 37 class Mutex;
gustavatmel 1:9c5af431a1f1 38 /** Typedef for the mutex lock
gustavatmel 1:9c5af431a1f1 39 *
gustavatmel 1:9c5af431a1f1 40 * Usage:
gustavatmel 1:9c5af431a1f1 41 * @code
gustavatmel 1:9c5af431a1f1 42 * void foo(Mutex &m) {
gustavatmel 1:9c5af431a1f1 43 * ScopedMutexLock lock(m);
gustavatmel 1:9c5af431a1f1 44 * // Mutex lock protects code in this block
gustavatmel 1:9c5af431a1f1 45 * }
gustavatmel 1:9c5af431a1f1 46 * @endcode
gustavatmel 1:9c5af431a1f1 47 */
gustavatmel 1:9c5af431a1f1 48 typedef mbed::ScopedLock<Mutex> ScopedMutexLock;
gustavatmel 1:9c5af431a1f1 49
gustavatmel 1:9c5af431a1f1 50 /**
gustavatmel 1:9c5af431a1f1 51 * \defgroup rtos_Mutex Mutex class
gustavatmel 1:9c5af431a1f1 52 * @{
gustavatmel 1:9c5af431a1f1 53 */
gustavatmel 1:9c5af431a1f1 54
gustavatmel 1:9c5af431a1f1 55 /** The Mutex class is used to synchronize the execution of threads.
gustavatmel 1:9c5af431a1f1 56 This is for example used to protect access to a shared resource.
gustavatmel 1:9c5af431a1f1 57
gustavatmel 1:9c5af431a1f1 58 @note You cannot use member functions of this class in ISR context. If you require Mutex functionality within
gustavatmel 1:9c5af431a1f1 59 ISR handler, consider using @a Semaphore.
gustavatmel 1:9c5af431a1f1 60
gustavatmel 1:9c5af431a1f1 61 @note
gustavatmel 1:9c5af431a1f1 62 Memory considerations: The mutex control structures will be created on current thread's stack, both for the Mbed OS
gustavatmel 1:9c5af431a1f1 63 and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
gustavatmel 1:9c5af431a1f1 64 */
gustavatmel 1:9c5af431a1f1 65 class Mutex : private mbed::NonCopyable<Mutex> {
gustavatmel 1:9c5af431a1f1 66 public:
gustavatmel 1:9c5af431a1f1 67 /** Create and Initialize a Mutex object
gustavatmel 1:9c5af431a1f1 68 *
gustavatmel 1:9c5af431a1f1 69 * @note You cannot call this function from ISR context.
gustavatmel 1:9c5af431a1f1 70 */
gustavatmel 1:9c5af431a1f1 71 Mutex();
gustavatmel 1:9c5af431a1f1 72
gustavatmel 1:9c5af431a1f1 73 /** Create and Initialize a Mutex object
gustavatmel 1:9c5af431a1f1 74
gustavatmel 1:9c5af431a1f1 75 @param name name to be used for this mutex. It has to stay allocated for the lifetime of the thread.
gustavatmel 1:9c5af431a1f1 76
gustavatmel 1:9c5af431a1f1 77 @note You cannot call this function from ISR context.
gustavatmel 1:9c5af431a1f1 78 */
gustavatmel 1:9c5af431a1f1 79 Mutex(const char *name);
gustavatmel 1:9c5af431a1f1 80
gustavatmel 1:9c5af431a1f1 81 /** Wait until a Mutex becomes available.
gustavatmel 1:9c5af431a1f1 82 @param millisec timeout value or 0 in case of no time-out. (default: osWaitForever)
gustavatmel 1:9c5af431a1f1 83 @return status code that indicates the execution status of the function:
gustavatmel 1:9c5af431a1f1 84 @a osOK the mutex has been obtained.
gustavatmel 1:9c5af431a1f1 85 @a osErrorTimeout the mutex could not be obtained in the given time.
gustavatmel 1:9c5af431a1f1 86 @a osErrorParameter internal error.
gustavatmel 1:9c5af431a1f1 87 @a osErrorResource the mutex could not be obtained when no timeout was specified.
gustavatmel 1:9c5af431a1f1 88 @a osErrorISR this function cannot be called from the interrupt service routine.
gustavatmel 1:9c5af431a1f1 89
gustavatmel 1:9c5af431a1f1 90 @note You cannot call this function from ISR context.
gustavatmel 1:9c5af431a1f1 91 */
gustavatmel 1:9c5af431a1f1 92 osStatus lock(uint32_t millisec=osWaitForever);
gustavatmel 1:9c5af431a1f1 93
gustavatmel 1:9c5af431a1f1 94 /** Try to lock the mutex, and return immediately
gustavatmel 1:9c5af431a1f1 95 @return true if the mutex was acquired, false otherwise.
gustavatmel 1:9c5af431a1f1 96 @note equivalent to trylock_for(0)
gustavatmel 1:9c5af431a1f1 97
gustavatmel 1:9c5af431a1f1 98 @note You cannot call this function from ISR context.
gustavatmel 1:9c5af431a1f1 99 */
gustavatmel 1:9c5af431a1f1 100 bool trylock();
gustavatmel 1:9c5af431a1f1 101
gustavatmel 1:9c5af431a1f1 102 /** Try to lock the mutex for a specified time
gustavatmel 1:9c5af431a1f1 103 @param millisec timeout value or 0 in case of no time-out.
gustavatmel 1:9c5af431a1f1 104 @return true if the mutex was acquired, false otherwise.
gustavatmel 1:9c5af431a1f1 105 @note the underlying RTOS may have a limit to the maximum wait time
gustavatmel 1:9c5af431a1f1 106 due to internal 32-bit computations, but this is guaranteed to work if the
gustavatmel 1:9c5af431a1f1 107 wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
gustavatmel 1:9c5af431a1f1 108 the lock attempt will time out earlier than specified.
gustavatmel 1:9c5af431a1f1 109
gustavatmel 1:9c5af431a1f1 110 @note You cannot call this function from ISR context.
gustavatmel 1:9c5af431a1f1 111 */
gustavatmel 1:9c5af431a1f1 112 bool trylock_for(uint32_t millisec);
gustavatmel 1:9c5af431a1f1 113
gustavatmel 1:9c5af431a1f1 114 /** Try to lock the mutex until specified time
gustavatmel 1:9c5af431a1f1 115 @param millisec absolute timeout time, referenced to Kernel::get_ms_count()
gustavatmel 1:9c5af431a1f1 116 @return true if the mutex was acquired, false otherwise.
gustavatmel 1:9c5af431a1f1 117 @note the underlying RTOS may have a limit to the maximum wait time
gustavatmel 1:9c5af431a1f1 118 due to internal 32-bit computations, but this is guaranteed to work if the
gustavatmel 1:9c5af431a1f1 119 wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
gustavatmel 1:9c5af431a1f1 120 the lock attempt will time out earlier than specified.
gustavatmel 1:9c5af431a1f1 121
gustavatmel 1:9c5af431a1f1 122 @note You cannot call this function from ISR context.
gustavatmel 1:9c5af431a1f1 123 */
gustavatmel 1:9c5af431a1f1 124 bool trylock_until(uint64_t millisec);
gustavatmel 1:9c5af431a1f1 125
gustavatmel 1:9c5af431a1f1 126 /** Unlock the mutex that has previously been locked by the same thread
gustavatmel 1:9c5af431a1f1 127 @return status code that indicates the execution status of the function:
gustavatmel 1:9c5af431a1f1 128 @a osOK the mutex has been released.
gustavatmel 1:9c5af431a1f1 129 @a osErrorParameter internal error.
gustavatmel 1:9c5af431a1f1 130 @a osErrorResource the mutex was not locked or the current thread wasn't the owner.
gustavatmel 1:9c5af431a1f1 131 @a osErrorISR this function cannot be called from the interrupt service routine.
gustavatmel 1:9c5af431a1f1 132
gustavatmel 1:9c5af431a1f1 133 @note You cannot call this function from ISR context.
gustavatmel 1:9c5af431a1f1 134 */
gustavatmel 1:9c5af431a1f1 135 osStatus unlock();
gustavatmel 1:9c5af431a1f1 136
gustavatmel 1:9c5af431a1f1 137 /** Get the owner the this mutex
gustavatmel 1:9c5af431a1f1 138 @return the current owner of this mutex.
gustavatmel 1:9c5af431a1f1 139
gustavatmel 1:9c5af431a1f1 140 @note You cannot call this function from ISR context.
gustavatmel 1:9c5af431a1f1 141 */
gustavatmel 1:9c5af431a1f1 142 osThreadId get_owner();
gustavatmel 1:9c5af431a1f1 143
gustavatmel 1:9c5af431a1f1 144 /** Mutex destructor
gustavatmel 1:9c5af431a1f1 145 *
gustavatmel 1:9c5af431a1f1 146 * @note You cannot call this function from ISR context.
gustavatmel 1:9c5af431a1f1 147 */
gustavatmel 1:9c5af431a1f1 148 ~Mutex();
gustavatmel 1:9c5af431a1f1 149
gustavatmel 1:9c5af431a1f1 150 private:
gustavatmel 1:9c5af431a1f1 151 void constructor(const char *name = NULL);
gustavatmel 1:9c5af431a1f1 152 friend class ConditionVariable;
gustavatmel 1:9c5af431a1f1 153
gustavatmel 1:9c5af431a1f1 154 osMutexId_t _id;
gustavatmel 1:9c5af431a1f1 155 mbed_rtos_storage_mutex_t _obj_mem;
gustavatmel 1:9c5af431a1f1 156 uint32_t _count;
gustavatmel 1:9c5af431a1f1 157 };
gustavatmel 1:9c5af431a1f1 158 /** @}*/
gustavatmel 1:9c5af431a1f1 159 /** @}*/
gustavatmel 1:9c5af431a1f1 160 }
gustavatmel 1:9c5af431a1f1 161 #endif
gustavatmel 1:9c5af431a1f1 162
gustavatmel 1:9c5af431a1f1 163