Denislam Valeev
/
Nucleo_rtos_basic
1
mbed-os/rtos/ConditionVariable.h@0:e056ac8fecf8, 2018-03-13 (annotated)
- Committer:
- valeyev
- Date:
- Tue Mar 13 07:17:50 2018 +0000
- Revision:
- 0:e056ac8fecf8
looking for...
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
valeyev | 0:e056ac8fecf8 | 1 | /* mbed Microcontroller Library |
valeyev | 0:e056ac8fecf8 | 2 | * Copyright (c) 2017-2017 ARM Limited |
valeyev | 0:e056ac8fecf8 | 3 | * |
valeyev | 0:e056ac8fecf8 | 4 | * Permission is hereby granted, free of charge, to any person obtaining a copy |
valeyev | 0:e056ac8fecf8 | 5 | * of this software and associated documentation files (the "Software"), to deal |
valeyev | 0:e056ac8fecf8 | 6 | * in the Software without restriction, including without limitation the rights |
valeyev | 0:e056ac8fecf8 | 7 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
valeyev | 0:e056ac8fecf8 | 8 | * copies of the Software, and to permit persons to whom the Software is |
valeyev | 0:e056ac8fecf8 | 9 | * furnished to do so, subject to the following conditions: |
valeyev | 0:e056ac8fecf8 | 10 | * |
valeyev | 0:e056ac8fecf8 | 11 | * The above copyright notice and this permission notice shall be included in |
valeyev | 0:e056ac8fecf8 | 12 | * all copies or substantial portions of the Software. |
valeyev | 0:e056ac8fecf8 | 13 | * |
valeyev | 0:e056ac8fecf8 | 14 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
valeyev | 0:e056ac8fecf8 | 15 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
valeyev | 0:e056ac8fecf8 | 16 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
valeyev | 0:e056ac8fecf8 | 17 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
valeyev | 0:e056ac8fecf8 | 18 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
valeyev | 0:e056ac8fecf8 | 19 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
valeyev | 0:e056ac8fecf8 | 20 | * SOFTWARE. |
valeyev | 0:e056ac8fecf8 | 21 | */ |
valeyev | 0:e056ac8fecf8 | 22 | #ifndef CONDITIONVARIABLE_H |
valeyev | 0:e056ac8fecf8 | 23 | #define CONDITIONVARIABLE_H |
valeyev | 0:e056ac8fecf8 | 24 | |
valeyev | 0:e056ac8fecf8 | 25 | #include <stdint.h> |
valeyev | 0:e056ac8fecf8 | 26 | #include "cmsis_os.h" |
valeyev | 0:e056ac8fecf8 | 27 | #include "rtos/Mutex.h" |
valeyev | 0:e056ac8fecf8 | 28 | #include "rtos/Semaphore.h" |
valeyev | 0:e056ac8fecf8 | 29 | |
valeyev | 0:e056ac8fecf8 | 30 | #include "platform/NonCopyable.h" |
valeyev | 0:e056ac8fecf8 | 31 | |
valeyev | 0:e056ac8fecf8 | 32 | namespace rtos { |
valeyev | 0:e056ac8fecf8 | 33 | /** \addtogroup rtos */ |
valeyev | 0:e056ac8fecf8 | 34 | /** @{*/ |
valeyev | 0:e056ac8fecf8 | 35 | |
valeyev | 0:e056ac8fecf8 | 36 | struct Waiter; |
valeyev | 0:e056ac8fecf8 | 37 | |
valeyev | 0:e056ac8fecf8 | 38 | /** This class provides a safe way to wait for or send notifications of condition changes |
valeyev | 0:e056ac8fecf8 | 39 | * |
valeyev | 0:e056ac8fecf8 | 40 | * This class is used in conjunction with a mutex to safely wait for or |
valeyev | 0:e056ac8fecf8 | 41 | * notify waiters of condition changes to a resource accessible by multiple |
valeyev | 0:e056ac8fecf8 | 42 | * threads. |
valeyev | 0:e056ac8fecf8 | 43 | * |
valeyev | 0:e056ac8fecf8 | 44 | * # Defined behavior |
valeyev | 0:e056ac8fecf8 | 45 | * - All threads waiting on the condition variable wake when |
valeyev | 0:e056ac8fecf8 | 46 | * ConditionVariable::notify_all is called. |
valeyev | 0:e056ac8fecf8 | 47 | * - If one or more threads are waiting on the condition variable at least |
valeyev | 0:e056ac8fecf8 | 48 | * one of them wakes when ConditionVariable::notify is called. |
valeyev | 0:e056ac8fecf8 | 49 | * |
valeyev | 0:e056ac8fecf8 | 50 | * # Undefined behavior |
valeyev | 0:e056ac8fecf8 | 51 | * - The thread which is unblocked on ConditionVariable::notify_one is |
valeyev | 0:e056ac8fecf8 | 52 | * undefined if there are multiple waiters. |
valeyev | 0:e056ac8fecf8 | 53 | * - The order which in which waiting threads acquire the condition variable's |
valeyev | 0:e056ac8fecf8 | 54 | * mutex after ConditionVariable::notify_all is called is undefined. |
valeyev | 0:e056ac8fecf8 | 55 | * - When ConditionVariable::notify_one or ConditionVariable::notify_all is |
valeyev | 0:e056ac8fecf8 | 56 | * called and there are one or more waiters and one or more threads attempting |
valeyev | 0:e056ac8fecf8 | 57 | * to acquire the condition variable's mutex the order in which the mutex is |
valeyev | 0:e056ac8fecf8 | 58 | * acquired is undefined. |
valeyev | 0:e056ac8fecf8 | 59 | * - The behavior of ConditionVariable::wait and ConditionVariable::wait_for |
valeyev | 0:e056ac8fecf8 | 60 | * is undefined if the condition variable's mutex is locked more than once by |
valeyev | 0:e056ac8fecf8 | 61 | * the calling thread. |
valeyev | 0:e056ac8fecf8 | 62 | * - Spurious notifications (not triggered by the application) can occur |
valeyev | 0:e056ac8fecf8 | 63 | * and it is not defined when these occur. |
valeyev | 0:e056ac8fecf8 | 64 | * |
valeyev | 0:e056ac8fecf8 | 65 | * @note Synchronization level: Thread safe |
valeyev | 0:e056ac8fecf8 | 66 | * |
valeyev | 0:e056ac8fecf8 | 67 | * Example: |
valeyev | 0:e056ac8fecf8 | 68 | * @code |
valeyev | 0:e056ac8fecf8 | 69 | * #include "mbed.h" |
valeyev | 0:e056ac8fecf8 | 70 | * |
valeyev | 0:e056ac8fecf8 | 71 | * Mutex mutex; |
valeyev | 0:e056ac8fecf8 | 72 | * ConditionVariable cond(mutex); |
valeyev | 0:e056ac8fecf8 | 73 | * |
valeyev | 0:e056ac8fecf8 | 74 | * // These variables are protected by locking mutex |
valeyev | 0:e056ac8fecf8 | 75 | * uint32_t count = 0; |
valeyev | 0:e056ac8fecf8 | 76 | * bool done = false; |
valeyev | 0:e056ac8fecf8 | 77 | * |
valeyev | 0:e056ac8fecf8 | 78 | * void worker_thread() |
valeyev | 0:e056ac8fecf8 | 79 | * { |
valeyev | 0:e056ac8fecf8 | 80 | * mutex.lock(); |
valeyev | 0:e056ac8fecf8 | 81 | * do { |
valeyev | 0:e056ac8fecf8 | 82 | * printf("Worker: Count %lu\r\n", count); |
valeyev | 0:e056ac8fecf8 | 83 | * |
valeyev | 0:e056ac8fecf8 | 84 | * // Wait for a condition to change |
valeyev | 0:e056ac8fecf8 | 85 | * cond.wait(); |
valeyev | 0:e056ac8fecf8 | 86 | * |
valeyev | 0:e056ac8fecf8 | 87 | * } while (!done); |
valeyev | 0:e056ac8fecf8 | 88 | * printf("Worker: Exiting\r\n"); |
valeyev | 0:e056ac8fecf8 | 89 | * mutex.unlock(); |
valeyev | 0:e056ac8fecf8 | 90 | * } |
valeyev | 0:e056ac8fecf8 | 91 | * |
valeyev | 0:e056ac8fecf8 | 92 | * int main() { |
valeyev | 0:e056ac8fecf8 | 93 | * Thread thread; |
valeyev | 0:e056ac8fecf8 | 94 | * thread.start(worker_thread); |
valeyev | 0:e056ac8fecf8 | 95 | * |
valeyev | 0:e056ac8fecf8 | 96 | * for (int i = 0; i < 5; i++) { |
valeyev | 0:e056ac8fecf8 | 97 | * |
valeyev | 0:e056ac8fecf8 | 98 | * mutex.lock(); |
valeyev | 0:e056ac8fecf8 | 99 | * // Change count and notify waiters of this |
valeyev | 0:e056ac8fecf8 | 100 | * count++; |
valeyev | 0:e056ac8fecf8 | 101 | * printf("Main: Set count to %lu\r\n", count); |
valeyev | 0:e056ac8fecf8 | 102 | * cond.notify_all(); |
valeyev | 0:e056ac8fecf8 | 103 | * mutex.unlock(); |
valeyev | 0:e056ac8fecf8 | 104 | * |
valeyev | 0:e056ac8fecf8 | 105 | * wait(1.0); |
valeyev | 0:e056ac8fecf8 | 106 | * } |
valeyev | 0:e056ac8fecf8 | 107 | * |
valeyev | 0:e056ac8fecf8 | 108 | * mutex.lock(); |
valeyev | 0:e056ac8fecf8 | 109 | * // Change done and notify waiters of this |
valeyev | 0:e056ac8fecf8 | 110 | * done = true; |
valeyev | 0:e056ac8fecf8 | 111 | * printf("Main: Set done\r\n"); |
valeyev | 0:e056ac8fecf8 | 112 | * cond.notify_all(); |
valeyev | 0:e056ac8fecf8 | 113 | * mutex.unlock(); |
valeyev | 0:e056ac8fecf8 | 114 | * |
valeyev | 0:e056ac8fecf8 | 115 | * thread.join(); |
valeyev | 0:e056ac8fecf8 | 116 | * } |
valeyev | 0:e056ac8fecf8 | 117 | * @endcode |
valeyev | 0:e056ac8fecf8 | 118 | */ |
valeyev | 0:e056ac8fecf8 | 119 | class ConditionVariable : private mbed::NonCopyable<ConditionVariable> { |
valeyev | 0:e056ac8fecf8 | 120 | public: |
valeyev | 0:e056ac8fecf8 | 121 | /** Create and Initialize a ConditionVariable object |
valeyev | 0:e056ac8fecf8 | 122 | * |
valeyev | 0:e056ac8fecf8 | 123 | * @note You cannot call this function from ISR context. |
valeyev | 0:e056ac8fecf8 | 124 | */ |
valeyev | 0:e056ac8fecf8 | 125 | ConditionVariable(Mutex &mutex); |
valeyev | 0:e056ac8fecf8 | 126 | |
valeyev | 0:e056ac8fecf8 | 127 | /** Wait for a notification |
valeyev | 0:e056ac8fecf8 | 128 | * |
valeyev | 0:e056ac8fecf8 | 129 | * Wait until a notification occurs. |
valeyev | 0:e056ac8fecf8 | 130 | * |
valeyev | 0:e056ac8fecf8 | 131 | * @note - The thread calling this function must be the owner of the |
valeyev | 0:e056ac8fecf8 | 132 | * ConditionVariable's mutex and it must be locked exactly once |
valeyev | 0:e056ac8fecf8 | 133 | * @note - Spurious notifications can occur so the caller of this API |
valeyev | 0:e056ac8fecf8 | 134 | * should check to make sure the condition they are waiting on has |
valeyev | 0:e056ac8fecf8 | 135 | * been met |
valeyev | 0:e056ac8fecf8 | 136 | * |
valeyev | 0:e056ac8fecf8 | 137 | * Example: |
valeyev | 0:e056ac8fecf8 | 138 | * @code |
valeyev | 0:e056ac8fecf8 | 139 | * mutex.lock(); |
valeyev | 0:e056ac8fecf8 | 140 | * while (!condition_met) { |
valeyev | 0:e056ac8fecf8 | 141 | * cond.wait(); |
valeyev | 0:e056ac8fecf8 | 142 | * } |
valeyev | 0:e056ac8fecf8 | 143 | * |
valeyev | 0:e056ac8fecf8 | 144 | * function_to_handle_condition(); |
valeyev | 0:e056ac8fecf8 | 145 | * |
valeyev | 0:e056ac8fecf8 | 146 | * mutex.unlock(); |
valeyev | 0:e056ac8fecf8 | 147 | * @endcode |
valeyev | 0:e056ac8fecf8 | 148 | * |
valeyev | 0:e056ac8fecf8 | 149 | * @note You cannot call this function from ISR context. |
valeyev | 0:e056ac8fecf8 | 150 | */ |
valeyev | 0:e056ac8fecf8 | 151 | void wait(); |
valeyev | 0:e056ac8fecf8 | 152 | |
valeyev | 0:e056ac8fecf8 | 153 | /** Wait for a notification until specified time |
valeyev | 0:e056ac8fecf8 | 154 | * |
valeyev | 0:e056ac8fecf8 | 155 | * @param millisec absolute end time referenced to Kernel::get_ms_count() |
valeyev | 0:e056ac8fecf8 | 156 | * @return true if a timeout occurred, false otherwise. |
valeyev | 0:e056ac8fecf8 | 157 | * |
valeyev | 0:e056ac8fecf8 | 158 | * @note - The thread calling this function must be the owner of the |
valeyev | 0:e056ac8fecf8 | 159 | * ConditionVariable's mutex and it must be locked exactly once |
valeyev | 0:e056ac8fecf8 | 160 | * @note - Spurious notifications can occur so the caller of this API |
valeyev | 0:e056ac8fecf8 | 161 | * should check to make sure the condition they are waiting on has |
valeyev | 0:e056ac8fecf8 | 162 | * been met |
valeyev | 0:e056ac8fecf8 | 163 | * |
valeyev | 0:e056ac8fecf8 | 164 | * Example: |
valeyev | 0:e056ac8fecf8 | 165 | * @code |
valeyev | 0:e056ac8fecf8 | 166 | * mutex.lock(); |
valeyev | 0:e056ac8fecf8 | 167 | * uint64_t end_time = Kernel::get_ms_count() + COND_WAIT_TIMEOUT; |
valeyev | 0:e056ac8fecf8 | 168 | * |
valeyev | 0:e056ac8fecf8 | 169 | * while (!condition_met) { |
valeyev | 0:e056ac8fecf8 | 170 | * if (cond.wait_until(end_time)) { |
valeyev | 0:e056ac8fecf8 | 171 | * break; |
valeyev | 0:e056ac8fecf8 | 172 | * } |
valeyev | 0:e056ac8fecf8 | 173 | * } |
valeyev | 0:e056ac8fecf8 | 174 | * |
valeyev | 0:e056ac8fecf8 | 175 | * if (condition_met) { |
valeyev | 0:e056ac8fecf8 | 176 | * function_to_handle_condition(); |
valeyev | 0:e056ac8fecf8 | 177 | * } |
valeyev | 0:e056ac8fecf8 | 178 | * |
valeyev | 0:e056ac8fecf8 | 179 | * mutex.unlock(); |
valeyev | 0:e056ac8fecf8 | 180 | * @endcode |
valeyev | 0:e056ac8fecf8 | 181 | * |
valeyev | 0:e056ac8fecf8 | 182 | * @note You cannot call this function from ISR context. |
valeyev | 0:e056ac8fecf8 | 183 | */ |
valeyev | 0:e056ac8fecf8 | 184 | bool wait_until(uint64_t millisec); |
valeyev | 0:e056ac8fecf8 | 185 | |
valeyev | 0:e056ac8fecf8 | 186 | /** Wait for a notification or timeout |
valeyev | 0:e056ac8fecf8 | 187 | * |
valeyev | 0:e056ac8fecf8 | 188 | * @param millisec timeout value or osWaitForever in case of no time-out. |
valeyev | 0:e056ac8fecf8 | 189 | * @return true if a timeout occurred, false otherwise. |
valeyev | 0:e056ac8fecf8 | 190 | * |
valeyev | 0:e056ac8fecf8 | 191 | * @note - The thread calling this function must be the owner of the |
valeyev | 0:e056ac8fecf8 | 192 | * ConditionVariable's mutex and it must be locked exactly once |
valeyev | 0:e056ac8fecf8 | 193 | * @note - Spurious notifications can occur so the caller of this API |
valeyev | 0:e056ac8fecf8 | 194 | * should check to make sure the condition they are waiting on has |
valeyev | 0:e056ac8fecf8 | 195 | * been met |
valeyev | 0:e056ac8fecf8 | 196 | * |
valeyev | 0:e056ac8fecf8 | 197 | * Example: |
valeyev | 0:e056ac8fecf8 | 198 | * @code |
valeyev | 0:e056ac8fecf8 | 199 | * mutex.lock(); |
valeyev | 0:e056ac8fecf8 | 200 | * |
valeyev | 0:e056ac8fecf8 | 201 | * while (!condition_met) { |
valeyev | 0:e056ac8fecf8 | 202 | * cond.wait_for(MAX_SLEEP_TIME); |
valeyev | 0:e056ac8fecf8 | 203 | * if (!condition_met) { |
valeyev | 0:e056ac8fecf8 | 204 | * do_other_work_while_condition_false(); |
valeyev | 0:e056ac8fecf8 | 205 | * } |
valeyev | 0:e056ac8fecf8 | 206 | * } |
valeyev | 0:e056ac8fecf8 | 207 | * |
valeyev | 0:e056ac8fecf8 | 208 | * if (condition_met) { |
valeyev | 0:e056ac8fecf8 | 209 | * function_to_handle_condition(); |
valeyev | 0:e056ac8fecf8 | 210 | * } |
valeyev | 0:e056ac8fecf8 | 211 | * |
valeyev | 0:e056ac8fecf8 | 212 | * mutex.unlock(); |
valeyev | 0:e056ac8fecf8 | 213 | * @endcode |
valeyev | 0:e056ac8fecf8 | 214 | * |
valeyev | 0:e056ac8fecf8 | 215 | * @note You cannot call this function from ISR context. |
valeyev | 0:e056ac8fecf8 | 216 | */ |
valeyev | 0:e056ac8fecf8 | 217 | bool wait_for(uint32_t millisec); |
valeyev | 0:e056ac8fecf8 | 218 | |
valeyev | 0:e056ac8fecf8 | 219 | /** Notify one waiter on this condition variable that a condition changed. |
valeyev | 0:e056ac8fecf8 | 220 | * |
valeyev | 0:e056ac8fecf8 | 221 | * @note - The thread calling this function must be the owner of the ConditionVariable's mutex |
valeyev | 0:e056ac8fecf8 | 222 | * |
valeyev | 0:e056ac8fecf8 | 223 | * @note You cannot call this function from ISR context. |
valeyev | 0:e056ac8fecf8 | 224 | */ |
valeyev | 0:e056ac8fecf8 | 225 | void notify_one(); |
valeyev | 0:e056ac8fecf8 | 226 | |
valeyev | 0:e056ac8fecf8 | 227 | /** Notify all waiters on this condition variable that a condition changed. |
valeyev | 0:e056ac8fecf8 | 228 | * |
valeyev | 0:e056ac8fecf8 | 229 | * @note - The thread calling this function must be the owner of the ConditionVariable's mutex |
valeyev | 0:e056ac8fecf8 | 230 | * |
valeyev | 0:e056ac8fecf8 | 231 | * @note You cannot call this function from ISR context. |
valeyev | 0:e056ac8fecf8 | 232 | */ |
valeyev | 0:e056ac8fecf8 | 233 | void notify_all(); |
valeyev | 0:e056ac8fecf8 | 234 | |
valeyev | 0:e056ac8fecf8 | 235 | /** ConditionVariable destructor |
valeyev | 0:e056ac8fecf8 | 236 | * |
valeyev | 0:e056ac8fecf8 | 237 | * @note You cannot call this function from ISR context. |
valeyev | 0:e056ac8fecf8 | 238 | */ |
valeyev | 0:e056ac8fecf8 | 239 | ~ConditionVariable(); |
valeyev | 0:e056ac8fecf8 | 240 | |
valeyev | 0:e056ac8fecf8 | 241 | protected: |
valeyev | 0:e056ac8fecf8 | 242 | struct Waiter { |
valeyev | 0:e056ac8fecf8 | 243 | Waiter(); |
valeyev | 0:e056ac8fecf8 | 244 | Semaphore sem; |
valeyev | 0:e056ac8fecf8 | 245 | Waiter *prev; |
valeyev | 0:e056ac8fecf8 | 246 | Waiter *next; |
valeyev | 0:e056ac8fecf8 | 247 | bool in_list; |
valeyev | 0:e056ac8fecf8 | 248 | }; |
valeyev | 0:e056ac8fecf8 | 249 | |
valeyev | 0:e056ac8fecf8 | 250 | static void _add_wait_list(Waiter **wait_list, Waiter *waiter); |
valeyev | 0:e056ac8fecf8 | 251 | static void _remove_wait_list(Waiter **wait_list, Waiter *waiter); |
valeyev | 0:e056ac8fecf8 | 252 | Mutex &_mutex; |
valeyev | 0:e056ac8fecf8 | 253 | Waiter *_wait_list; |
valeyev | 0:e056ac8fecf8 | 254 | }; |
valeyev | 0:e056ac8fecf8 | 255 | |
valeyev | 0:e056ac8fecf8 | 256 | } |
valeyev | 0:e056ac8fecf8 | 257 | #endif |
valeyev | 0:e056ac8fecf8 | 258 | |
valeyev | 0:e056ac8fecf8 | 259 | /** @}*/ |