From 9d71bbc9f67478ccc28bf6ea9cb1617e8293be94 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 25 Mar 2024 21:11:43 -0700 Subject: More updates --- docs/reference/src/api/nng_bus_open.md | 40 -------------- docs/reference/src/api/nng_close.md | 45 ---------------- docs/reference/src/api/nng_cv_alloc.md | 46 ---------------- docs/reference/src/api/nng_cv_free.md | 22 -------- docs/reference/src/api/nng_cv_until.md | 75 -------------------------- docs/reference/src/api/nng_cv_wait.md | 68 ----------------------- docs/reference/src/api/nng_cv_wake.md | 42 --------------- docs/reference/src/api/nng_cv_wake1.md | 43 --------------- docs/reference/src/api/protocol.md | 1 - docs/reference/src/api/socket/index.md | 1 + docs/reference/src/api/socket/nng_bus_open.md | 40 ++++++++++++++ docs/reference/src/api/socket/nng_close.md | 45 ++++++++++++++++ docs/reference/src/api/socket/nng_pub_open.md | 53 ++++++++++++++++++ docs/reference/src/api/threads/nng_cv_alloc.md | 46 ++++++++++++++++ docs/reference/src/api/threads/nng_cv_free.md | 22 ++++++++ docs/reference/src/api/threads/nng_cv_until.md | 75 ++++++++++++++++++++++++++ docs/reference/src/api/threads/nng_cv_wait.md | 68 +++++++++++++++++++++++ docs/reference/src/api/threads/nng_cv_wake.md | 42 +++++++++++++++ docs/reference/src/api/threads/nng_cv_wake1.md | 43 +++++++++++++++ docs/reference/src/api/util/nng_random.md | 45 ++++++++++++++++ docs/reference/src/api/util/nng_strerror.md | 48 +++++++++++++++++ 21 files changed, 528 insertions(+), 382 deletions(-) delete mode 100644 docs/reference/src/api/nng_bus_open.md delete mode 100644 docs/reference/src/api/nng_close.md delete mode 100644 docs/reference/src/api/nng_cv_alloc.md delete mode 100644 docs/reference/src/api/nng_cv_free.md delete mode 100644 docs/reference/src/api/nng_cv_until.md delete mode 100644 docs/reference/src/api/nng_cv_wait.md delete mode 100644 docs/reference/src/api/nng_cv_wake.md delete mode 100644 docs/reference/src/api/nng_cv_wake1.md delete mode 100644 docs/reference/src/api/protocol.md create mode 100644 docs/reference/src/api/socket/index.md create mode 100644 docs/reference/src/api/socket/nng_bus_open.md create mode 100644 docs/reference/src/api/socket/nng_close.md create mode 100644 docs/reference/src/api/socket/nng_pub_open.md create mode 100644 docs/reference/src/api/threads/nng_cv_alloc.md create mode 100644 docs/reference/src/api/threads/nng_cv_free.md create mode 100644 docs/reference/src/api/threads/nng_cv_until.md create mode 100644 docs/reference/src/api/threads/nng_cv_wait.md create mode 100644 docs/reference/src/api/threads/nng_cv_wake.md create mode 100644 docs/reference/src/api/threads/nng_cv_wake1.md create mode 100644 docs/reference/src/api/util/nng_random.md create mode 100644 docs/reference/src/api/util/nng_strerror.md (limited to 'docs/reference') diff --git a/docs/reference/src/api/nng_bus_open.md b/docs/reference/src/api/nng_bus_open.md deleted file mode 100644 index a579acfb..00000000 --- a/docs/reference/src/api/nng_bus_open.md +++ /dev/null @@ -1,40 +0,0 @@ -# nng_bus_open() - -## NAME - -nng_bus_open --- create bus socket - -## SYNOPSIS - -```c -#include -#include - -int nng_bus0_open(nng_socket *s); - -int nng_bus0_open_raw(nng_socket *s); -``` - -## DESCRIPTION - -The `nng_bus0_open()` function creates a [_BUS_](../protocols/bus.md) version 0 -[socket](nng_socket.md) and returns it at the location pointed to by _s_. - -The `nng_bus0_open_raw()` function creates a [_BUS_](../protocols/bus.md) version 0 -[socket](nng_socket.md) in -[raw](../overview/raw.md) mode, and returns it at the location pointed to by _s_. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient memory is available. -- `NNG_ENOTSUP`: The protocol is not supported. - -## SEE ALSO - -[nng_socket()](nng_socket.md), -[BUS protocol](../protocols/bus.md), -[RAW mode](../overview/raw.md) diff --git a/docs/reference/src/api/nng_close.md b/docs/reference/src/api/nng_close.md deleted file mode 100644 index 486cfe2c..00000000 --- a/docs/reference/src/api/nng_close.md +++ /dev/null @@ -1,45 +0,0 @@ -# nng_close(3) - -## NAME - -nng_close --- close socket - -## SYNOPSIS - -```c -#include - -int nng_close(nng_socket s); -``` - -## DESCRIPTION - -The `nng_close()` function closes the supplied socket, _s_. -Messages that have been submitted for sending may be flushed or delivered, -depending upon the transport. - -Further attempts to use the socket after this call returns will result -in `NNG_ECLOSED`. -Threads waiting for operations on the socket when this -call is executed may also return with an `NNG_ECLOSED` result. - -> [!NOTE] -> Closing the socket while data is in transmission will likely lead to loss -> of that data. -> There is no automatic linger or flush to ensure that the socket send buffers -> have completely transmitted. -> It is recommended to wait a brief period after calling -> [`nng_send()`](nng_send.md) or similar functions, before calling this -> function. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ECLOSED`: The socket _s_ is already closed or was never opened. - -## SEE ALSO - -[nng_socket](nng_socket.md) diff --git a/docs/reference/src/api/nng_cv_alloc.md b/docs/reference/src/api/nng_cv_alloc.md deleted file mode 100644 index 7379df7e..00000000 --- a/docs/reference/src/api/nng_cv_alloc.md +++ /dev/null @@ -1,46 +0,0 @@ -# nng_cv_alloc() - -## NAME - -nng_cv_alloc --- allocate condition variable - -## SYNOPSIS - -```c -#include -#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 -[`nng_cv_wait()`](nng_cv_wait.md) or -[`nng_cv_until()`](nng_cv_until.md). -The mutex must also be owned when signaling the condition using the -[`nng_cv_wake()`](nng_cv_wake.md) or -[`nng_cv_wake1()`](nng_cv_wake1.md) functions. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_cv_free()](nng_cv_free.md), -[nng_cv_until()](nng_cv_until.md), -[nng_cv_wait()](nng_cv_wait.md), -[nng_cv_wake()](nng_cv_wake.md), -[nng_cv_wake1()](nng_cv_wake1.md), -[nng_mtx_alloc()](nng_mtx_alloc.md) diff --git a/docs/reference/src/api/nng_cv_free.md b/docs/reference/src/api/nng_cv_free.md deleted file mode 100644 index 87412ce9..00000000 --- a/docs/reference/src/api/nng_cv_free.md +++ /dev/null @@ -1,22 +0,0 @@ -# nng_cv_free() - -## NAME - -nng_cv_free --- free condition variable - -### SYNOPSIS - -```c -#include -#include - -void nng_cv_free(nng_cv *cv); -``` - -## DESCRIPTION - -The `nng_cv_free()` function frees the condition variable _cv_. - -## SEE ALSO - -[nng_cv_alloc()](nng_cv_alloc.md) diff --git a/docs/reference/src/api/nng_cv_until.md b/docs/reference/src/api/nng_cv_until.md deleted file mode 100644 index 34669953..00000000 --- a/docs/reference/src/api/nng_cv_until.md +++ /dev/null @@ -1,75 +0,0 @@ -# nng_cv_until() - -## NAME - -nng_cv_until --- wait for condition or timeout - -## SYNOPSIS - -```c -#include -#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 -[`nng_cv_wake()`](nng_cv_wake.md) or -[`nng_cv_wake1()`](nng_cv_wake1.md), or the system clock (as tracked -by [`nng_clock()`](nng_clock.md)) 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.) - -Spurious wakeups can occur. - -> [!TIP] -> 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 - -```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 - -```c - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); -``` - -## SEE ALSO - -[nng_clock()](nng_clock.md), -[nng_cv_alloc()](nng_cv_alloc.md), -[nng_cv_wait()](nng_cv_wait.md), -[nng_cv_wake()](nng_cv_wake.md), -[nng_cv_wake1()](nng_cv_wake1.md), -[nng_mtx_alloc()](nng_mtx_alloc.md), -[nng_mtx_lock()](nng_mtx_lock.md), -[nng_mtx_unlock()](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/nng_cv_wait.md b/docs/reference/src/api/nng_cv_wait.md deleted file mode 100644 index 1f4ddf42..00000000 --- a/docs/reference/src/api/nng_cv_wait.md +++ /dev/null @@ -1,68 +0,0 @@ -# nng_cv_wait() - -## NAME - -nng_cv_wait --- wait for condition - -## SYNOPSIS - -```c -#include -#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 [`nng_cv_wake()`](nng_cv_wake.md) or -[`nng_cv_wake1()`](nng_cv_wake1.md). - -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.) - -Spurious wakeups are possible. - -> [!TIP] -> 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 - -```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 - -```c - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); -``` - -## SEE ALSO - -[nng_cv_alloc()](nng_cv_alloc.md), -[nng_cv_until()](nng_cv_until.md), -[nng_cv_wake()](nng_cv_wake.md), -[nng_cv_wake1()](nng_cv_wake1.md), -[nng_mtx_alloc()](nng_mtx_alloc.md), -[nng_mtx_lock()](nng_mtx_lock.md), -[nng_mtx_unlock()](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/nng_cv_wake.md b/docs/reference/src/api/nng_cv_wake.md deleted file mode 100644 index e83fa96d..00000000 --- a/docs/reference/src/api/nng_cv_wake.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_cv_wake() - -## NAME - -nng_cv_wake --- wake all waiters - -## SYNOPSIS - -```c -#include -#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 [`nng_cv_wait()`](nng_cv_wait.md) or -[`nng_cv_until()`](nng_cv_until.md) functions. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. - -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 [`nng_cv_wake1()`](nng_cv_wake1.md) for a solution to this problem. - -## SEE ALSO - -[nng_cv_alloc()](nng_cv_alloc.md), -[nng_cv_until()](nng_cv_until.md), -[nng_cv_wait()](nng_cv_wait.md), -[nng_cv_wake1()](nng_cv_wake1.md), -[nng_mtx_alloc()](nng_mtx_alloc.md), -[nng_mtx_lock()](nng_mtx_lock.md), -[nng_mtx_unlock()](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/nng_cv_wake1.md b/docs/reference/src/api/nng_cv_wake1.md deleted file mode 100644 index 1c70388d..00000000 --- a/docs/reference/src/api/nng_cv_wake1.md +++ /dev/null @@ -1,43 +0,0 @@ -# nng_cv_wake1() - -## NAME - -nng_cv_wake1 --- wake one waiter - -## SYNOPSIS - -```c -#include -#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 [`nng_cv_wait()`](nng_cv_wait.md) or -[`nng_cv_until()`](nng_cv_until.md) functions. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. - -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 [`nng_cv_wake()`](nng_cv_wake.md). - -## SEE ALSO - -[.text-left] -[nng_cv_alloc()](nng_cv_alloc.md), -[nng_cv_until()](nng_cv_until.md), -[nng_cv_wait()](nng_cv_wait.md), -[nng_cv_wake()](nng_cv_wake.md), -[nng_mtx_alloc()](nng_mtx_alloc.md), -[nng_mtx_lock()](nng_mtx_lock.md), -[nng_mtx_unlock()](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/protocol.md b/docs/reference/src/api/protocol.md deleted file mode 100644 index 990b7cbb..00000000 --- a/docs/reference/src/api/protocol.md +++ /dev/null @@ -1 +0,0 @@ -# Protocol Sockets diff --git a/docs/reference/src/api/socket/index.md b/docs/reference/src/api/socket/index.md new file mode 100644 index 00000000..990b7cbb --- /dev/null +++ b/docs/reference/src/api/socket/index.md @@ -0,0 +1 @@ +# Protocol Sockets diff --git a/docs/reference/src/api/socket/nng_bus_open.md b/docs/reference/src/api/socket/nng_bus_open.md new file mode 100644 index 00000000..a579acfb --- /dev/null +++ b/docs/reference/src/api/socket/nng_bus_open.md @@ -0,0 +1,40 @@ +# nng_bus_open() + +## NAME + +nng_bus_open --- create bus socket + +## SYNOPSIS + +```c +#include +#include + +int nng_bus0_open(nng_socket *s); + +int nng_bus0_open_raw(nng_socket *s); +``` + +## DESCRIPTION + +The `nng_bus0_open()` function creates a [_BUS_](../protocols/bus.md) version 0 +[socket](nng_socket.md) and returns it at the location pointed to by _s_. + +The `nng_bus0_open_raw()` function creates a [_BUS_](../protocols/bus.md) version 0 +[socket](nng_socket.md) in +[raw](../overview/raw.md) mode, and returns it at the location pointed to by _s_. + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient memory is available. +- `NNG_ENOTSUP`: The protocol is not supported. + +## SEE ALSO + +[nng_socket()](nng_socket.md), +[BUS protocol](../protocols/bus.md), +[RAW mode](../overview/raw.md) diff --git a/docs/reference/src/api/socket/nng_close.md b/docs/reference/src/api/socket/nng_close.md new file mode 100644 index 00000000..486cfe2c --- /dev/null +++ b/docs/reference/src/api/socket/nng_close.md @@ -0,0 +1,45 @@ +# nng_close(3) + +## NAME + +nng_close --- close socket + +## SYNOPSIS + +```c +#include + +int nng_close(nng_socket s); +``` + +## DESCRIPTION + +The `nng_close()` function closes the supplied socket, _s_. +Messages that have been submitted for sending may be flushed or delivered, +depending upon the transport. + +Further attempts to use the socket after this call returns will result +in `NNG_ECLOSED`. +Threads waiting for operations on the socket when this +call is executed may also return with an `NNG_ECLOSED` result. + +> [!NOTE] +> Closing the socket while data is in transmission will likely lead to loss +> of that data. +> There is no automatic linger or flush to ensure that the socket send buffers +> have completely transmitted. +> It is recommended to wait a brief period after calling +> [`nng_send()`](nng_send.md) or similar functions, before calling this +> function. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ECLOSED`: The socket _s_ is already closed or was never opened. + +## SEE ALSO + +[nng_socket](nng_socket.md) diff --git a/docs/reference/src/api/socket/nng_pub_open.md b/docs/reference/src/api/socket/nng_pub_open.md new file mode 100644 index 00000000..c9f3b5b5 --- /dev/null +++ b/docs/reference/src/api/socket/nng_pub_open.md @@ -0,0 +1,53 @@ += nng_pub_open(3) +// +// Copyright 2018 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_pub_open - create pub socket + +== SYNOPSIS + +[source,c] +---- +#include +#include + +int nng_pub0_open(nng_socket *s); + +int nng_pub0_open_raw(nng_socket *s); +---- + +== DESCRIPTION + +The `nng_pub0_open()` function creates a xref:nng_pub.7.adoc[_pub_] version 0 +xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_. + +The `nng_pub0_open_raw()` function creates a xref:nng_pub.7.adoc[_pub_] version 0 +xref:nng_socket.5.adoc[socket] in +xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_. + +== RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient memory is available. +`NNG_ENOTSUP`:: The protocol is not supported. + +== SEE ALSO + +[.text-left] +xref:nng_socket.5.adoc[nng_socket(5)], +xref:nng_pub.7.adoc[nng_pub(7)], +xref:nng_sub.7.adoc[nng_sub(7)], +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/threads/nng_cv_alloc.md b/docs/reference/src/api/threads/nng_cv_alloc.md new file mode 100644 index 00000000..7379df7e --- /dev/null +++ b/docs/reference/src/api/threads/nng_cv_alloc.md @@ -0,0 +1,46 @@ +# nng_cv_alloc() + +## NAME + +nng_cv_alloc --- allocate condition variable + +## SYNOPSIS + +```c +#include +#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 +[`nng_cv_wait()`](nng_cv_wait.md) or +[`nng_cv_until()`](nng_cv_until.md). +The mutex must also be owned when signaling the condition using the +[`nng_cv_wake()`](nng_cv_wake.md) or +[`nng_cv_wake1()`](nng_cv_wake1.md) functions. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient free memory exists. + +## SEE ALSO + +[nng_cv_free()](nng_cv_free.md), +[nng_cv_until()](nng_cv_until.md), +[nng_cv_wait()](nng_cv_wait.md), +[nng_cv_wake()](nng_cv_wake.md), +[nng_cv_wake1()](nng_cv_wake1.md), +[nng_mtx_alloc()](nng_mtx_alloc.md) diff --git a/docs/reference/src/api/threads/nng_cv_free.md b/docs/reference/src/api/threads/nng_cv_free.md new file mode 100644 index 00000000..87412ce9 --- /dev/null +++ b/docs/reference/src/api/threads/nng_cv_free.md @@ -0,0 +1,22 @@ +# nng_cv_free() + +## NAME + +nng_cv_free --- free condition variable + +### SYNOPSIS + +```c +#include +#include + +void nng_cv_free(nng_cv *cv); +``` + +## DESCRIPTION + +The `nng_cv_free()` function frees the condition variable _cv_. + +## SEE ALSO + +[nng_cv_alloc()](nng_cv_alloc.md) diff --git a/docs/reference/src/api/threads/nng_cv_until.md b/docs/reference/src/api/threads/nng_cv_until.md new file mode 100644 index 00000000..34669953 --- /dev/null +++ b/docs/reference/src/api/threads/nng_cv_until.md @@ -0,0 +1,75 @@ +# nng_cv_until() + +## NAME + +nng_cv_until --- wait for condition or timeout + +## SYNOPSIS + +```c +#include +#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 +[`nng_cv_wake()`](nng_cv_wake.md) or +[`nng_cv_wake1()`](nng_cv_wake1.md), or the system clock (as tracked +by [`nng_clock()`](nng_clock.md)) 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.) + +Spurious wakeups can occur. + +> [!TIP] +> 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 + +```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 + +```c + nng_mtx_lock(m); + condition_true = true; + nng_cv_wake(cv); + nng_mtx_unlock(m); +``` + +## SEE ALSO + +[nng_clock()](nng_clock.md), +[nng_cv_alloc()](nng_cv_alloc.md), +[nng_cv_wait()](nng_cv_wait.md), +[nng_cv_wake()](nng_cv_wake.md), +[nng_cv_wake1()](nng_cv_wake1.md), +[nng_mtx_alloc()](nng_mtx_alloc.md), +[nng_mtx_lock()](nng_mtx_lock.md), +[nng_mtx_unlock()](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_cv_wait.md b/docs/reference/src/api/threads/nng_cv_wait.md new file mode 100644 index 00000000..1f4ddf42 --- /dev/null +++ b/docs/reference/src/api/threads/nng_cv_wait.md @@ -0,0 +1,68 @@ +# nng_cv_wait() + +## NAME + +nng_cv_wait --- wait for condition + +## SYNOPSIS + +```c +#include +#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 [`nng_cv_wake()`](nng_cv_wake.md) or +[`nng_cv_wake1()`](nng_cv_wake1.md). + +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.) + +Spurious wakeups are possible. + +> [!TIP] +> 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 + +```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 + +```c + nng_mtx_lock(m); + condition_true = true; + nng_cv_wake(cv); + nng_mtx_unlock(m); +``` + +## SEE ALSO + +[nng_cv_alloc()](nng_cv_alloc.md), +[nng_cv_until()](nng_cv_until.md), +[nng_cv_wake()](nng_cv_wake.md), +[nng_cv_wake1()](nng_cv_wake1.md), +[nng_mtx_alloc()](nng_mtx_alloc.md), +[nng_mtx_lock()](nng_mtx_lock.md), +[nng_mtx_unlock()](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_cv_wake.md b/docs/reference/src/api/threads/nng_cv_wake.md new file mode 100644 index 00000000..e83fa96d --- /dev/null +++ b/docs/reference/src/api/threads/nng_cv_wake.md @@ -0,0 +1,42 @@ +# nng_cv_wake() + +## NAME + +nng_cv_wake --- wake all waiters + +## SYNOPSIS + +```c +#include +#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 [`nng_cv_wait()`](nng_cv_wait.md) or +[`nng_cv_until()`](nng_cv_until.md) functions. + +The caller must have have ownership of the mutex that was used when +_cv_ was allocated. + +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 [`nng_cv_wake1()`](nng_cv_wake1.md) for a solution to this problem. + +## SEE ALSO + +[nng_cv_alloc()](nng_cv_alloc.md), +[nng_cv_until()](nng_cv_until.md), +[nng_cv_wait()](nng_cv_wait.md), +[nng_cv_wake1()](nng_cv_wake1.md), +[nng_mtx_alloc()](nng_mtx_alloc.md), +[nng_mtx_lock()](nng_mtx_lock.md), +[nng_mtx_unlock()](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_cv_wake1.md b/docs/reference/src/api/threads/nng_cv_wake1.md new file mode 100644 index 00000000..1c70388d --- /dev/null +++ b/docs/reference/src/api/threads/nng_cv_wake1.md @@ -0,0 +1,43 @@ +# nng_cv_wake1() + +## NAME + +nng_cv_wake1 --- wake one waiter + +## SYNOPSIS + +```c +#include +#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 [`nng_cv_wait()`](nng_cv_wait.md) or +[`nng_cv_until()`](nng_cv_until.md) functions. + +The caller must have have ownership of the mutex that was used when +_cv_ was allocated. + +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 [`nng_cv_wake()`](nng_cv_wake.md). + +## SEE ALSO + +[.text-left] +[nng_cv_alloc()](nng_cv_alloc.md), +[nng_cv_until()](nng_cv_until.md), +[nng_cv_wait()](nng_cv_wait.md), +[nng_cv_wake()](nng_cv_wake.md), +[nng_mtx_alloc()](nng_mtx_alloc.md), +[nng_mtx_lock()](nng_mtx_lock.md), +[nng_mtx_unlock()](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/util/nng_random.md b/docs/reference/src/api/util/nng_random.md new file mode 100644 index 00000000..3f8ac39e --- /dev/null +++ b/docs/reference/src/api/util/nng_random.md @@ -0,0 +1,45 @@ += nng_random(3supp) +// +// Copyright 2018 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_random - get random number + +== SYNOPSIS + +[source, c] +---- +#include +#include + +uint32_t nng_random(void); +---- + +== DESCRIPTION + +The `nng_random()` returns a random number. +The value returned is suitable for use with cryptographic functions such as +key generation. +The value is obtained using platform specific cryptographically strong random +number facilities when available. + +== RETURN VALUES + +Random number. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/api/util/nng_strerror.md b/docs/reference/src/api/util/nng_strerror.md new file mode 100644 index 00000000..145fd0bc --- /dev/null +++ b/docs/reference/src/api/util/nng_strerror.md @@ -0,0 +1,48 @@ += nng_strerror(3) +// +// Copyright 2018 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_strerror - return an error description + +== SYNOPSIS + +[source, c] +---- +#include + +const char * nng_strerror(int err); +---- + +== DESCRIPTION + +The `nng_strerror()` returns the human-readable description of the +given error in `err`. + +NOTE: The returned error message is provided in US English, but in the +future locale-specific strings may be presented instead. + +NOTE: The specific strings associated with specific error messages are +subject to change. +Therefore applications must not depend on the message, +but may use them verbatim when supplying information to end-users, such +as in diagnostic messages or log entries. + +== RETURN VALUES + +This function returns the human-readable error message, terminated +by a `NUL` byte. + +== SEE ALSO + +[.text-left] +xref:libnng.3.adoc[libnng(3)], +xref:nng.7.adoc[nng(7)] -- cgit v1.2.3-70-g09d2