diff options
Diffstat (limited to 'docs/reference/src/api/threads')
| -rw-r--r-- | docs/reference/src/api/threads/nng_cv_alloc.md | 46 | ||||
| -rw-r--r-- | docs/reference/src/api/threads/nng_cv_free.md | 22 | ||||
| -rw-r--r-- | docs/reference/src/api/threads/nng_cv_until.md | 75 | ||||
| -rw-r--r-- | docs/reference/src/api/threads/nng_cv_wait.md | 68 | ||||
| -rw-r--r-- | docs/reference/src/api/threads/nng_cv_wake.md | 42 | ||||
| -rw-r--r-- | docs/reference/src/api/threads/nng_cv_wake1.md | 42 | ||||
| -rw-r--r-- | docs/reference/src/api/threads/nng_mtx_alloc.md | 44 | ||||
| -rw-r--r-- | docs/reference/src/api/threads/nng_mtx_free.md | 23 | ||||
| -rw-r--r-- | docs/reference/src/api/threads/nng_mtx_lock.md | 38 | ||||
| -rw-r--r-- | docs/reference/src/api/threads/nng_mtx_unlock.md | 29 |
10 files changed, 0 insertions, 429 deletions
diff --git a/docs/reference/src/api/threads/nng_cv_alloc.md b/docs/reference/src/api/threads/nng_cv_alloc.md deleted file mode 100644 index faa18ba4..00000000 --- a/docs/reference/src/api/threads/nng_cv_alloc.md +++ /dev/null @@ -1,46 +0,0 @@ -# nng_cv_alloc - -## NAME - -nng_cv_alloc --- allocate condition variable - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.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 -[`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 deleted file mode 100644 index f7103f66..00000000 --- a/docs/reference/src/api/threads/nng_cv_free.md +++ /dev/null @@ -1,22 +0,0 @@ -# nng_cv_free - -## NAME - -nng_cv_free --- free condition variable - -### SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -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 deleted file mode 100644 index 620b46b7..00000000 --- a/docs/reference/src/api/threads/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 <nng/nng.h> -#include <nng/supplemental/util/platform.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 -[`nng_cv_wake()`](nng_cv_wake.md) or -[`nng_cv_wake1()`](nng_cv_wake1.md), or the system clock (as tracked -by [`nng_clock()`](../util/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()](../util/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 deleted file mode 100644 index d384201c..00000000 --- a/docs/reference/src/api/threads/nng_cv_wait.md +++ /dev/null @@ -1,68 +0,0 @@ -# nng_cv_wait - -## NAME - -nng_cv_wait --- wait for condition - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.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 [`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 deleted file mode 100644 index 8d0d2fbd..00000000 --- a/docs/reference/src/api/threads/nng_cv_wake.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_cv_wake - -## NAME - -nng_cv_wake --- wake all waiters - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.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 [`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 deleted file mode 100644 index 09b31755..00000000 --- a/docs/reference/src/api/threads/nng_cv_wake1.md +++ /dev/null @@ -1,42 +0,0 @@ -# nng_cv_wake1 - -## NAME - -nng_cv_wake1 --- wake one waiter - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.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 [`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 - -[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/threads/nng_mtx_alloc.md b/docs/reference/src/api/threads/nng_mtx_alloc.md deleted file mode 100644 index 64263d59..00000000 --- a/docs/reference/src/api/threads/nng_mtx_alloc.md +++ /dev/null @@ -1,44 +0,0 @@ -# nng_mtx_alloc - -## NAME - -nng_mtx_alloc - allocate mutex - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -typedef struct nng_mtx nng_mtx; - -int nng_mtx_alloc(nng_mtx **mtxp); -``` - -## DESCRIPTION - -The `nng_mtx_alloc()` function allocates mutex and returns it in _mtxp_. - -The mutex objects created by this function are suitable only for -simple lock and unlock operations, and are not recursive. -Every effort has been made to use light-weight underlying primitives when available. - -Mutex (mutual exclusion) objects can be thought of as binary semaphores, -where only a single thread of execution is permitted to acquire the semaphore. - -Furthermore, a mutex can only be unlocked by the thread that locked it. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory exists. - -## SEE ALSO - -[nng_cv_alloc](nng_cv_alloc.md), -[nng_mtx_free](nng_mtx_free.md), -[nng_mtx_lock](nng_mtx_lock.md), -[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_mtx_free.md b/docs/reference/src/api/threads/nng_mtx_free.md deleted file mode 100644 index a6fe7d7b..00000000 --- a/docs/reference/src/api/threads/nng_mtx_free.md +++ /dev/null @@ -1,23 +0,0 @@ -# nng_mtx_free - -## NAME - -nng_mtx_free --- free mutex - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -void nng_mtx_free(nng_mtx *mtx); -``` - -## DESCRIPTION - -The `nng_mtx_free()` function frees the mutex _mtx_. -The mutex must not be locked when this function is called. - -## SEE ALSO - -[nng_mtx_alloc](nng_mtx_alloc) diff --git a/docs/reference/src/api/threads/nng_mtx_lock.md b/docs/reference/src/api/threads/nng_mtx_lock.md deleted file mode 100644 index 2e50f010..00000000 --- a/docs/reference/src/api/threads/nng_mtx_lock.md +++ /dev/null @@ -1,38 +0,0 @@ -# nng_mtx_lock - -## NAME - -nng_mtx_lock --- lock mutex - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -void nng_mtx_lock(nng_mtx *mtx); -``` - -## DESCRIPTION - -The `nng_mtx_lock()` acquires exclusive ownership of the mutex _mtx_. -If the lock is already owned, this function will wait until the current -owner releases it with [`nng_mtx_unlock()`](nng_mtx_unlock.md). - -If multiple threads are waiting for the lock, the order of acquisition -is not specified. - -> [!NOTE] -> A mutex can _only_ be unlocked by the thread that locked it. - -> [!NOTE] -> Mutex locks are _not_ recursive; attempts to reacquire the -> same mutex may result in deadlock or aborting the current program. -> It is a programming error for the owner of a mutex to attempt to -> reacquire it. - -## SEE ALSO - -[nng_cv_alloc](nng_cv_alloc.md), -[nng_mtx_alloc](nng_mtx_alloc.md), -[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_mtx_unlock.md b/docs/reference/src/api/threads/nng_mtx_unlock.md deleted file mode 100644 index d5815287..00000000 --- a/docs/reference/src/api/threads/nng_mtx_unlock.md +++ /dev/null @@ -1,29 +0,0 @@ -# nng_mtx_unlock(3supp) - -## NAME - -nng_mtx_unlock --- unlock mutex - -## SYNOPSIS - -```c -#include <nng/nng.h> -#include <nng/supplemental/util/platform.h> - -void nng_mtx_unlock(nng_mtx *mtx); -``` - -## DESCRIPTION - -The `nng_mtx_unlock()` relinquishes ownership of the mutex _mtx_ that -was previously acquired via [`nng_mtx_lock()`](nng_mtx_lock.md). - -> [!NOTE] -> A mutex can _only_ be unlocked by the thread that locked it. -> Attempting to unlock a mutex that is not owned by the caller will result -> in undefined behavior. - -## SEE ALSO - -[nng_mtx_alloc](nng_mtx_alloc), -[nng_mtx_lock](nng_mtx_lock) |
