summaryrefslogtreecommitdiff
path: root/docs/reference/src/api/threads
diff options
context:
space:
mode:
Diffstat (limited to 'docs/reference/src/api/threads')
-rw-r--r--docs/reference/src/api/threads/nng_cv_alloc.md46
-rw-r--r--docs/reference/src/api/threads/nng_cv_free.md22
-rw-r--r--docs/reference/src/api/threads/nng_cv_until.md75
-rw-r--r--docs/reference/src/api/threads/nng_cv_wait.md68
-rw-r--r--docs/reference/src/api/threads/nng_cv_wake.md42
-rw-r--r--docs/reference/src/api/threads/nng_cv_wake1.md42
-rw-r--r--docs/reference/src/api/threads/nng_mtx_alloc.md44
-rw-r--r--docs/reference/src/api/threads/nng_mtx_free.md23
-rw-r--r--docs/reference/src/api/threads/nng_mtx_lock.md38
-rw-r--r--docs/reference/src/api/threads/nng_mtx_unlock.md29
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)