From d82509e810aea45454f9b3692c5577bd86cd65c7 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 11 Oct 2024 17:25:42 -0700 Subject: Converted condition variable docs to mdbook. This also is implemented using a single unified manual page that should be easier to reference. --- docs/man/libnng.3.adoc | 12 +++--- docs/man/nng_cv_alloc.3supp.adoc | 59 -------------------------- docs/man/nng_cv_free.3supp.adoc | 41 ------------------ docs/man/nng_cv_until.3supp.adoc | 90 ---------------------------------------- docs/man/nng_cv_wait.3supp.adoc | 85 ------------------------------------- docs/man/nng_cv_wake.3supp.adoc | 60 --------------------------- docs/man/nng_cv_wake1.3supp.adoc | 60 --------------------------- 7 files changed, 6 insertions(+), 401 deletions(-) delete mode 100644 docs/man/nng_cv_alloc.3supp.adoc delete mode 100644 docs/man/nng_cv_free.3supp.adoc delete mode 100644 docs/man/nng_cv_until.3supp.adoc delete mode 100644 docs/man/nng_cv_wait.3supp.adoc delete mode 100644 docs/man/nng_cv_wake.3supp.adoc delete mode 100644 docs/man/nng_cv_wake1.3supp.adoc (limited to 'docs/man') 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. -// Copyright 2018 Capitar IT Group BV -// -// 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 - -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. -// Copyright 2018 Capitar IT Group BV -// -// 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 - -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. -// Copyright 2018 Capitar IT Group BV -// -// 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 - -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. -// Copyright 2018 Capitar IT Group BV -// -// 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 - -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. -// Copyright 2018 Capitar IT Group BV -// -// 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 - -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. -// Copyright 2018 Capitar IT Group BV -// -// 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 - -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)] -- cgit v1.2.3-70-g09d2