ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Copy edit ConditionVariable.h 

Copy edit file, including existing text.
pull/8511/head
Amanda Butler 2018-10-23 15:34:16 -05:00 committed by GitHub
parent c86ceb1bc1
commit 8ddfdf5b2f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 25 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
rtos/ConditionVariable.h
View File

@ -44,10 +44,10 @@ struct Waiter;
* *
* The thread that intends to wait on a ConditionVariable must: * The thread that intends to wait on a ConditionVariable must:
* - Acquire a lock on a mutex * - Acquire a lock on a mutex
* - Execute `wait`, `wait_for`, or `wait_until`. While the thread is waiting, * - Execute `wait`, `wait_for` or `wait_until`. While the thread is waiting,
* the mutex will be unlocked. * the mutex will be unlocked.
* - When the condition variable has been notified, or in the case of `wait_for` * - When the condition variable has been notified, or in the case of `wait_for`
* and `wait_until` the timeout expires the thread is awakened. * and `wait_until` the timeout expires, the thread is awakened.
* *
* The thread that intends to notify a ConditionVariable must: * The thread that intends to notify a ConditionVariable must:
* - Acquire a lock on the mutex used to construct the condition variable. * - Acquire a lock on the mutex used to construct the condition variable.
@ -58,13 +58,13 @@ struct Waiter;
* ConditionVariable::notify_all is called. * ConditionVariable::notify_all is called.
* - At least one thread that is waiting on the condition variable will wake * - At least one thread that is waiting on the condition variable will wake
* when ConditionVariable::notify_one is called. * when ConditionVariable::notify_one is called.
* - While waiting for a thread is waiting for notification of a * - While a thread is waiting for notification of a
* ConditionVariable it will release the lock held on the mutex. * ConditionVariable, it will release the lock held on the mutex.
* - The ConditionVariable will reacquire the mutex lock before exiting the wait * - The ConditionVariable will reacquire the mutex lock before exiting the wait
* function. * function.
* *
* ## Undefined behavior * ## Undefined behavior
* - The thread which is unblocked on ConditionVariable::notify_one is * - The thread that is unblocked on ConditionVariable::notify_one is
* undefined if there are multiple waiters. * undefined if there are multiple waiters.
* - Calling wait if the mutex is not locked by the current thread is undefined * - Calling wait if the mutex is not locked by the current thread is undefined
* behavior. * behavior.
@ -72,12 +72,12 @@ struct Waiter;
* mutex after ConditionVariable::notify_all is called is undefined. * mutex after ConditionVariable::notify_all is called is undefined.
* - When ConditionVariable::notify_one or ConditionVariable::notify_all is * - When ConditionVariable::notify_one or ConditionVariable::notify_all is
* called and there are one or more waiters, and one or more threads * called and there are one or more waiters, and one or more threads
* attempting to acquire the condition variable's mutex the order in which the mutex is * attempting to acquire the condition variable's mutex, the order in which the mutex is
* acquired is undefined. * acquired is undefined.
* - The behavior of ConditionVariable::wait and ConditionVariable::wait_for * - The behavior of ConditionVariable::wait and ConditionVariable::wait_for
* is undefined if the condition variable's mutex is locked more than once by * is undefined if the condition variable's mutex is locked more than once by
* the calling thread. * the calling thread.
* - Spurious notifications (not triggered by the application) can occur * - Spurious notifications (not triggered by the application) can occur,
* and it is not defined when these occur. * and it is not defined when these occur.
* *
* @note Synchronization level: Thread safe * @note Synchronization level: Thread safe
@ -123,7 +123,7 @@ struct Waiter;
* // Acquire lock on mutex before modifying variables and notifying. * // Acquire lock on mutex before modifying variables and notifying.
* mutex.lock(); * mutex.lock();
* *
* // Change count and notify waiters of this * // Change count and notify waiters of this.
* work_count++; * work_count++;
* printf("Main thread: Set count to: %lu\r\n", work_count); * printf("Main thread: Set count to: %lu\r\n", work_count);
* printf("Main thread: Notifying worker thread\r\n"); * printf("Main thread: Notifying worker thread\r\n");
@ -135,7 +135,7 @@ struct Waiter;
* wait(1.0); * wait(1.0);
* } * }
* *
* // Change done and notify waiters of this * // Change done and notify waiters of this.
* mutex.lock(); * mutex.lock();
* done = true; * done = true;
* cv.notify_all(); * cv.notify_all();
@ -150,22 +150,22 @@ struct Waiter;
class ConditionVariable : private mbed::NonCopyable<ConditionVariable> { class ConditionVariable : private mbed::NonCopyable<ConditionVariable> {
public: public:
/** Create and initialize a ConditionVariable object /** Create and initialize a ConditionVariable object.
* *
* @note You cannot call this function from ISR context. * @note You cannot call this function from ISR context.
*/ */
ConditionVariable(Mutex &mutex); ConditionVariable(Mutex &mutex);
/** Wait for a notification /** Wait for a notification.
* *
* Wait causes the current thread to block until the condition variable * Wait causes the current thread to block until the condition variable
* receives a notification from another thread. * receives a notification from another thread.
* *
* @note - The thread calling this function must be the owner of the * @note - The thread calling this function must be the owner of the
* ConditionVariable's mutex and it must be locked exactly once. * ConditionVariable's mutex, and it must be locked exactly once.
* *
* @note - Spurious notifications can occur so the caller of this API * @note - Spurious notifications can occur, so the caller of this API
* should check to make sure the condition they are waiting on has * should check to make sure the condition the caller is waiting on has
* been met. * been met.
* *
* @note - The current thread will release the lock while inside the wait * @note - The current thread will release the lock while inside the wait
@ -188,7 +188,7 @@ public:
*/ */
void wait(); void wait();
/** Wait for a notification until specified time /** Wait for a notification until the specified time.
* *
* Wait until causes the current thread to block until the condition * Wait until causes the current thread to block until the condition
* variable is notified, or a specific time given by millisec parameter is * variable is notified, or a specific time given by millisec parameter is
@ -198,10 +198,10 @@ public:
* @return true if a timeout occurred, false otherwise. * @return true if a timeout occurred, false otherwise.
* *
* @note - The thread calling this function must be the owner of the * @note - The thread calling this function must be the owner of the
* ConditionVariable's mutex and it must be locked exactly once. * ConditionVariable's mutex, and it must be locked exactly once.
* *
* @note - Spurious notifications can occur so the caller of this API * @note - Spurious notifications can occur, so the caller of this API
* should check to make sure the condition they are waiting on has * should check to make sure the condition the caller is waiting on has
* been met. * been met.
* *
* @note - The current thread will release the lock while inside the wait * @note - The current thread will release the lock while inside the wait
@ -235,14 +235,14 @@ public:
* variable receives a notification from another thread, or the timeout * variable receives a notification from another thread, or the timeout
* specified by the millisec parameter is reached. * specified by the millisec parameter is reached.
* *
* @param millisec timeout value or osWaitForever in case of no time-out. * @param millisec timeout value or osWaitForever in case of no timeout.
* @return true if a timeout occurred, false otherwise. * @return true if a timeout occurred, false otherwise.
* *
* @note - The thread calling this function must be the owner of the * @note - The thread calling this function must be the owner of the
* ConditionVariable's mutex and it must be locked exactly once. * ConditionVariable's mutex, and it must be locked exactly once.
* *
* @note - Spurious notifications can occur so the caller of this API * @note - Spurious notifications can occur, so the caller of this API
* should check to make sure the condition they are waiting on has * should check to make sure the condition the caller is waiting on has
* been met. * been met.
* *
* @note - The current thread will release the lock while inside the wait * @note - The current thread will release the lock while inside the wait
@ -276,9 +276,9 @@ public:
* variable. * variable.
* *
* @note - The thread calling this function must be the owner of the * @note - The thread calling this function must be the owner of the
* ConditionVariable's mutex * ConditionVariable's mutex.
* *
* @note - The thread which is unblocked on ConditionVariable::notify_one is * @note - The thread that is unblocked on ConditionVariable::notify_one is
* undefined if there are multiple waiters. * undefined if there are multiple waiters.
* *
* @note You cannot call this function from ISR context. * @note You cannot call this function from ISR context.
@ -291,7 +291,7 @@ public:
* variable. * variable.
* *
* @note - The thread calling this function must be the owner of the * @note - The thread calling this function must be the owner of the
* ConditionVariable's mutex * ConditionVariable's mutex.
* *
* @note - If there are one or more waiters and one or more threads * @note - If there are one or more waiters and one or more threads
* attempting to acquire the condition variable's mutex the order in which * attempting to acquire the condition variable's mutex the order in which