diff options
Diffstat (limited to 'docs/ref/api/thr/nng_cv.md')
| -rw-r--r-- | docs/ref/api/thr/nng_cv.md | 115 |
1 files changed, 0 insertions, 115 deletions
diff --git a/docs/ref/api/thr/nng_cv.md b/docs/ref/api/thr/nng_cv.md deleted file mode 100644 index 29a149a0..00000000 --- a/docs/ref/api/thr/nng_cv.md +++ /dev/null @@ -1,115 +0,0 @@ -# nng_cv - -## NAME - -nng_cv --- condition variable - -## SYNOPSIS - -```c -#include <nng/nng.h> - -typedef struct nng_cv nng_cv; - -int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx); -void nng_cv_free(nng_cv *cv); -int nng_cv_until(nng_cv *cv, nng_time when); -void nng_cv_wait(nng_cv *cv); -void nng_cv_wake(nng_cv *cv); -void nng_cv_wake1(nng_cv *cv); -``` - -## DESCRIPTION - -The {{i:`nng_cv`}} structure implements a {{i:condition variable}}, associated with the -the [mutex][nng_mtx] _mtx_ which was supplied when it was created. - -Condition variables provide for a way to wait on an arbitrary condition, and to be woken -when the condition is signaled. -The mutex is dropped while the caller is asleep, and reacquired atomically when the caller -is woken. - -> [!IMPORTANT] -> -> The caller of `nng_cv_until`, `nng_cv_wait`, `nng_cv_wake`, and `nng_cv_wake1` _must_ -> have ownership of the mutex _mtx_ when calling these functions. - -### Initialization and Teardown - -The {{i:`nng_cv_alloc`}} function allocates a condition variable, and associated with the mutex _mtx_, -and returns a pointer to it in _cvp_. -The {{i:`nng_cv_free`}} function deallocates the condition variable _cv_. - -### Waiting for the Condition - -The {{i:`nng_cv_until`}} and {{i:`nng_cv_wait`}} functions put the caller to sleep until the condition -variable _cv_ is signaled, or (in the case of `nng_cv_until`), the specified time _when_ -(as determined by [`nng_clock`][nng_clock] is reached. - -While `nng_cv_wait` never fails and so has no return value, the `nng_cv_until` function can -return `NNG_ETIMEDOUT` if the time is reached before condition _cv_ is signaled by -either `nng_cv_wake` or `nng_cv_wake1`. - -### Signaling the Condition - -The {{i:`nng_cv_wake`}} and {{i:`nng_cv_wake1`}} functions wake threads waiting in -`nng_cv_until` or `nng_cv_wake`. The difference between these functions is that -`nng_cv_wake` will wake _every_ thread, whereas `nng_cv_wake1` will wake up exactly -one thread (which may be chosen randomly). - -> [!TIP] -> Use of `nng_cv_wake1` may be used to reduce the "thundering herd" syndrom of waking -> all threads concurrently, but should only be used in circumstances where the application -> does not depend on _which_ thread will be woken. When in doubt, `nng_cv_wake` is safer. - -## EXAMPLE - -### Example 1: Allocating the condition variable - -```c - nng_mtx *m; - nng_cv *cv; - nng_mtx_alloc(&m); // error checks elided - nng_cv_alloc(&cv, m); -``` - -### Example 2: Waiting for the condition - -```c - expire = nng_clock() + 1000; // 1 second in the future - nng_mtx_lock(m); // assume cv was allocated using m - while (!condition_true) { - if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) { - printf("Time out reached!\n"); - break; - } - } - // condition_true is true - nng_mtx_unlock(m); -``` - -### Example 3: Signaling the condition - -```c - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); -``` - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. -- `NNG_ETIMEDOUT`: The time specified by _when_ is reached without the condition being signaled. - -## SEE ALSO - -[nng_clock][nng_clock], -[nng_mtx][nng_mtx] - -[nng_clock]: ../util/nng_clock.md -[nng_mtx]: ../thr/nng_mtx.md |
