diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/man/libnng.3.adoc | 12 | ||||
| -rw-r--r-- | docs/man/nng_cv_alloc.3supp.adoc | 59 | ||||
| -rw-r--r-- | docs/man/nng_cv_free.3supp.adoc | 41 | ||||
| -rw-r--r-- | docs/man/nng_cv_until.3supp.adoc | 90 | ||||
| -rw-r--r-- | docs/man/nng_cv_wait.3supp.adoc | 85 | ||||
| -rw-r--r-- | docs/man/nng_cv_wake.3supp.adoc | 60 | ||||
| -rw-r--r-- | docs/man/nng_cv_wake1.3supp.adoc | 60 | ||||
| -rw-r--r-- | docs/ref/SUMMARY.md | 1 | ||||
| -rw-r--r-- | docs/ref/api/thr/index.md | 1 | ||||
| -rw-r--r-- | docs/ref/api/thr/nng_cv.md | 115 | ||||
| -rw-r--r-- | docs/ref/api/thr/nng_mtx.md | 2 |
11 files changed, 124 insertions, 402 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index c6c5b311..b787c7e8 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -283,12 +283,12 @@ as a convenience to aid in creating portable applications. |=== // |xref:nng_clock.3supp.adoc[nng_clock()]|get time -|xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc()]|allocate condition variable -|xref:nng_cv_free.3supp.adoc[nng_cv_free()]|free condition variable -|xref:nng_cv_until.3supp.adoc[nng_cv_until()]|wait for condition or timeout -|xref:nng_cv_wait.3supp.adoc[nng_cv_wait()]|wait for condition -|xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters -|xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter +// |xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc()]|allocate condition variable +// |xref:nng_cv_free.3supp.adoc[nng_cv_free()]|free condition variable +// |xref:nng_cv_until.3supp.adoc[nng_cv_until()]|wait for condition or timeout +// |xref:nng_cv_wait.3supp.adoc[nng_cv_wait()]|wait for condition +// |xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters +// |xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter // |xref:nng_id_map.3supp.adoc[nng_id_map]|identifier based mapping table // |xref:nng_msleep.3supp.adoc[nng_msleep()]|sleep for milliseconds // |xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc()]|allocate mutex diff --git a/docs/man/nng_cv_alloc.3supp.adoc b/docs/man/nng_cv_alloc.3supp.adoc deleted file mode 100644 index f87f70f8..00000000 --- a/docs/man/nng_cv_alloc.3supp.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nng_cv_alloc(3supp) -// -// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_alloc - allocate condition variable - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -typedef struct nng_cv nng_cv; - -int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx); ----- - -== DESCRIPTION - -The `nng_cv_alloc()` function allocates a condition variable, using -the mutex _mtx_, and returns it in _cvp_. - -Every condition variable is associated with a mutex, which must be -owned when a thread waits for the condition using -xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or -xref:nng_cv_until.3supp.adoc[`nng_cv_until()`]. -The mutex must also be owned when signaling the condition using the -xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or -xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`] functions. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -xref:nng_cv_free.3supp.adoc[nng_cv_free(3supp)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], -xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], -xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_free.3supp.adoc b/docs/man/nng_cv_free.3supp.adoc deleted file mode 100644 index 82eeb033..00000000 --- a/docs/man/nng_cv_free.3supp.adoc +++ /dev/null @@ -1,41 +0,0 @@ -= nng_cv_free(3supp) -// -// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_free - free condition variable - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -void nng_cv_free(nng_cv *cv); ----- - -== DESCRIPTION - -The `nng_cv_free()` function frees the condition variable _cv_. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_until.3supp.adoc b/docs/man/nng_cv_until.3supp.adoc deleted file mode 100644 index a168599d..00000000 --- a/docs/man/nng_cv_until.3supp.adoc +++ /dev/null @@ -1,90 +0,0 @@ -= nng_cv_until(3supp) -// -// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_until - wait for condition or timeout - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -int nng_cv_until(nng_cv *cv, nng_time when); ----- - -== DESCRIPTION - -The `nng_cv_until()` waits until either the condition variable _cv_ is signaled -by another thread calling either xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or -xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`], or the system clock (as tracked -by xref:nng_clock.3supp.adoc[`nng_clock()`]) reaches _when_. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. -This function will drop the ownership of that mutex, and reacquire it -atomically just before returning to the caller. -(The waiting is done without holding the mutex.) - -NOTE: Any condition may be used or checked, but the condition must be -checked, as it is possible for this function to wake up spuriously. -The best way to do this is inside a loop that repeats until the condition -tests for true. - -== EXAMPLE - -The following example demonstrates use of this function: - -.Example 1: Waiting for the condition -[source, 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 2: Signaling the condition -[source, c] ----- - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); ----- - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], -xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], -xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_wait.3supp.adoc b/docs/man/nng_cv_wait.3supp.adoc deleted file mode 100644 index 9078ac44..00000000 --- a/docs/man/nng_cv_wait.3supp.adoc +++ /dev/null @@ -1,85 +0,0 @@ -= nng_cv_wait(3supp) -// -// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_wait - wait for condition - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -void nng_cv_wait(nng_cv *cv); ----- - -== DESCRIPTION - -The `nng_cv_wait()` waits for the condition variable _cv_ to be signaled -by another thread calling either xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or -xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`]. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. -This function will drop the ownership of that mutex, and reacquire it -atomically just before returning to the caller. -(The waiting is done without holding the mutex.) - -NOTE: Any condition may be used or checked, but the condition must be -checked, as it is possible for this function to wake up spuriously. -The best way to do this is inside a loop that repeats until the condition -tests for true. - -== EXAMPLE - -The following example demonstrates use of this function: - -.Example 1: Waiting for the condition -[source, c] ----- - - nng_mtx_lock(m); // assume cv was allocated using m - while (!condition_true) { - nng_cv_wait(cv); - } - // condition_true is true - nng_mtx_unlock(m); ----- - -.Example 2: Signaling the condition -[source, c] ----- - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); ----- - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], -xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_wake.3supp.adoc b/docs/man/nng_cv_wake.3supp.adoc deleted file mode 100644 index a4fe2eca..00000000 --- a/docs/man/nng_cv_wake.3supp.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_cv_wake(3supp) -// -// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_wake - wake all waiters - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -void nng_cv_wake(nng_cv *cv); ----- - -== DESCRIPTION - -The `nng_cv_wake()` wakes any threads waiting for the condition variable _cv_ -to be signaled in the xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or -xref:nng_cv_until.3supp.adoc[`nng_cv_until()`] functions. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. - -NOTE: The caller should already have set the condition that the waiters -will check, while holding the mutex. - -TIP: This function wakes all threads, which is generally safer but can -lead to a performance problem when there are many waiters, as they are all -woken simultaneously and may contend for resources. -See xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`] for a solution to this problem. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], -xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_wake1.3supp.adoc b/docs/man/nng_cv_wake1.3supp.adoc deleted file mode 100644 index de556698..00000000 --- a/docs/man/nng_cv_wake1.3supp.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_cv_wake1(3supp) -// -// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_wake1 - wake one waiter - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -void nng_cv_wake1(nng_cv *cv); ----- - -== DESCRIPTION - -The `nng_cv_wake1()` wakes at most one thread waiting for the condition -variable _cv_ -to be signaled in the xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or -xref:nng_cv_until.3supp.adoc[`nng_cv_until()`] functions. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. - -NOTE: The caller should already have set the condition that the waiters -will check, while holding the mutex. - -NOTE: The caller cannot predict which waiter will be woken, and so the design must -ensure that it is sufficient that _any_ waiter be woken. -When in doubt, it is safer to use xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`]. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], -xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index ac627ee4..1d7065c2 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -4,6 +4,7 @@ - [Threading Functions](./api/thr/index.md) + - [nng_cv](./api/thr/nng_cv.md) - [nng_mtx](./api/thr/nng_mtx.md) - [Utility Functions](./api/util/index.md) diff --git a/docs/ref/api/thr/index.md b/docs/ref/api/thr/index.md index d9d168ac..6355cfef 100644 --- a/docs/ref/api/thr/index.md +++ b/docs/ref/api/thr/index.md @@ -1,3 +1,4 @@ # Threading Functions +- [nng_cv](nng_cv.md) - [nng_mtx](nng_mtx.md) diff --git a/docs/ref/api/thr/nng_cv.md b/docs/ref/api/thr/nng_cv.md new file mode 100644 index 00000000..29a149a0 --- /dev/null +++ b/docs/ref/api/thr/nng_cv.md @@ -0,0 +1,115 @@ +# 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 diff --git a/docs/ref/api/thr/nng_mtx.md b/docs/ref/api/thr/nng_mtx.md index 37249e4f..02735423 100644 --- a/docs/ref/api/thr/nng_mtx.md +++ b/docs/ref/api/thr/nng_mtx.md @@ -1,4 +1,4 @@ -# nng_id_map +# nng_mutex ## NAME |