6 files changed, 296 insertions, 0 deletions
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 <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
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 <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
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 <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()`](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 <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
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 <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
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 <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
+
+[.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)