Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update documentation for the ConditionVariable API #8511

Merged
merged 5 commits into from Oct 27, 2018
Merged

Update documentation for the ConditionVariable API #8511

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c86ceb1
docs(api-condvar): Update documentation for the ConditionVariable API
Oct 23, 2018
8ddfdf5
Copy edit ConditionVariable.h
Oct 23, 2018
5cc5e47
future to present tense
Oct 25, 2018
c8f9759
Adding punctuation
Oct 25, 2018
98e6d53
Capitalization, header level adjustment
Oct 25, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions rtos/ConditionVariable.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/* mbed Microcontroller Library
* Copyright (c) 2017-2017 ARM Limited
/* Mbed Microcontroller Library
* Copyright (c) 2017-2018 ARM Limited
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
Expand Down Expand Up @@ -38,32 +38,32 @@ struct Waiter;
/** The ConditionVariable class is a synchronization primitive that allows
* threads to wait until a particular condition occurs.
*
* The condition variable is used in conjunction with a mutex to safely wait for
* Use the condition variable in conjunction with a mutex to safely wait for
* or notify waiters of condition changes to a resource accessible by multiple
* threads.
*
* The thread that intends to wait on a ConditionVariable must:
* - Acquire a lock on a mutex
* - Execute `wait`, `wait_for` or `wait_until`. While the thread is waiting,
* the mutex will be unlocked.
* the mutex is unlocked.
* - When the condition variable has been notified, or in the case of `wait_for`
* and `wait_until` the timeout expires, the thread is awakened.
*
* The thread that intends to notify a ConditionVariable must:
* - Acquire a lock on the mutex used to construct the condition variable.
* - Execute `notify_one` or `notify_all` on the condition variable.
*
* ## Defined behavior
* - All threads that are waiting on the condition variable will wake when
* ConditionVariable::notify_all is called.
* - At least one thread that is waiting on the condition variable will wake
* when ConditionVariable::notify_one is called.
* ### Defined behavior
* - All threads waiting on the condition variable wake when
* `ConditionVariable::notify_all` is called.
* - At least one thread waiting on the condition variable wakes
* when `ConditionVariable::notify_one` is called.
* - While a thread is waiting for notification of a
* ConditionVariable, it will release the lock held on the mutex.
* - The ConditionVariable will reacquire the mutex lock before exiting the wait
* ConditionVariable, it releases the lock held on the mutex.
* - The ConditionVariable reacquires the mutex lock before exiting the wait
* function.
*
* ## Undefined behavior
* ### Undefined behavior
* - The thread that is unblocked on ConditionVariable::notify_one is
* undefined if there are multiple waiters.
melwee01 marked this conversation as resolved.
Show resolved Hide resolved
* - Calling wait if the mutex is not locked by the current thread is undefined
Expand Down Expand Up @@ -167,8 +167,8 @@ class ConditionVariable : private mbed::NonCopyable<ConditionVariable> {
* @note - Spurious notifications can occur, so the caller of this API
* should check to make sure the condition the caller is waiting on has
* been met.
*
* @note - The current thread will release the lock while inside the wait
*
* @note - The current thread releases the lock while inside the wait
kjbracey marked this conversation as resolved.
Show resolved Hide resolved
* function and reacquire it upon exiting the function.
*
* Example:
Expand Down Expand Up @@ -204,7 +204,7 @@ class ConditionVariable : private mbed::NonCopyable<ConditionVariable> {
* should check to make sure the condition the caller is waiting on has
* been met.
*
* @note - The current thread will release the lock while inside the wait
* @note - The current thread releases the lock while inside the wait
* function and reacquire it upon exiting the function.
*
* Example:
Expand Down Expand Up @@ -245,7 +245,7 @@ class ConditionVariable : private mbed::NonCopyable<ConditionVariable> {
* should check to make sure the condition the caller is waiting on has
* been met.
*
* @note - The current thread will release the lock while inside the wait
* @note - The current thread releases the lock while inside the wait
* function and reacquire it upon exiting the function.
*
* Example:
Expand All @@ -272,7 +272,7 @@ class ConditionVariable : private mbed::NonCopyable<ConditionVariable> {

/** Notify one waiter on this condition variable that a condition changed.
*
* This function will unblock one of the threads waiting for the condition
* This function unblocks one of the threads waiting for the condition
* variable.
*
* @note - The thread calling this function must be the owner of the
Expand All @@ -287,7 +287,7 @@ class ConditionVariable : private mbed::NonCopyable<ConditionVariable> {

/** Notify all waiters on this condition variable that a condition changed.
*
* This function will unblock all of the threads waiting for the condition
* This function unblocks all of the threads waiting for the condition
* variable.
*
* @note - The thread calling this function must be the owner of the
Expand Down