aboutsummaryrefslogtreecommitdiff
path: root/docs/ref/api/thr/nng_cv.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/ref/api/thr/nng_cv.md')
-rw-r--r--docs/ref/api/thr/nng_cv.md115
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