Organization changes abound.

10 files changed, 449 insertions, 0 deletions

diff --git a/docs/reference/src/thr/nng_cv_alloc.md b/docs/reference/src/thr/nng_cv_alloc.md
new file mode 100644
index 00000000..8545958a
--- /dev/null
+++ b/docs/reference/src/thr/nng_cv_alloc.md
@@ -0,0 +1,48 @@
+# 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 {{i: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] or
+[`nng_cv_until()`][nng_cv_until].
+The mutex must also be owned when signaling the condition using the
+[`nng_cv_wake()`][nng_cv_wake] or
+[`nng_cv_wake1()`][nng_cv_wake1] 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],
+[nng_cv_until][nng_cv_until],
+[nng_cv_wait][nng_cv_wait],
+[nng_cv_wake][nng_cv_wake],
+[nng_cv_wake1][nng_cv_wake1],
+[nng_mtx_alloc][nng_mtx_alloc]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/thr/nng_cv_free.md b/docs/reference/src/thr/nng_cv_free.md
new file mode 100644
index 00000000..d2de68af
--- /dev/null
+++ b/docs/reference/src/thr/nng_cv_free.md
@@ -0,0 +1,24 @@
+# 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]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/thr/nng_cv_until.md b/docs/reference/src/thr/nng_cv_until.md
new file mode 100644
index 00000000..dde512c1
--- /dev/null
+++ b/docs/reference/src/thr/nng_cv_until.md
@@ -0,0 +1,77 @@
+# 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] or
+[`nng_cv_wake1()`][nng_cv_wake1], 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],
+[nng_cv_wait()][nng_cv_wait],
+[nng_cv_wake()][nng_cv_wake],
+[nng_cv_wake1()][nng_cv_wake1],
+[nng_mtx_alloc()][nng_mtx_alloc],
+[nng_mtx_lock()][nng_mtx_lock],
+[nng_mtx_unlock()][nng_mtx_unlock]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/thr/nng_cv_wait.md b/docs/reference/src/thr/nng_cv_wait.md
new file mode 100644
index 00000000..bf5f13a5
--- /dev/null
+++ b/docs/reference/src/thr/nng_cv_wait.md
@@ -0,0 +1,70 @@
+# 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] or
+[`nng_cv_wake1()`][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.)
+
+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],
+[nng_cv_until][nng_cv_until],
+[nng_cv_wake][nng_cv_wake],
+[nng_cv_wake1][nng_cv_wake1],
+[nng_mtx_alloc][nng_mtx_alloc],
+[nng_mtx_lock][nng_mtx_lock],
+[nng_mtx_unlock][nng_mtx_unlock]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/thr/nng_cv_wake.md b/docs/reference/src/thr/nng_cv_wake.md
new file mode 100644
index 00000000..b01f27d5
--- /dev/null
+++ b/docs/reference/src/thr/nng_cv_wake.md
@@ -0,0 +1,44 @@
+# 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] or
+[`nng_cv_until()`][nng_cv_until] 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] for a solution to this problem.
+
+## SEE ALSO
+
+[nng_cv_alloc][nng_cv_alloc],
+[nng_cv_until][nng_cv_until],
+[nng_cv_wait][nng_cv_wait],
+[nng_cv_wake1][nng_cv_wake1],
+[nng_mtx_alloc][nng_mtx_alloc],
+[nng_mtx_lock][nng_mtx_lock],
+[nng_mtx_unlock][nng_mtx_unlock]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/thr/nng_cv_wake1.md b/docs/reference/src/thr/nng_cv_wake1.md
new file mode 100644
index 00000000..4464d9bb
--- /dev/null
+++ b/docs/reference/src/thr/nng_cv_wake1.md
@@ -0,0 +1,44 @@
+# 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] or
+[`nng_cv_until()`][nng_cv_until] 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].
+
+## SEE ALSO
+
+[nng_cv_alloc][nng_cv_alloc],
+[nng_cv_until][nng_cv_until],
+[nng_cv_wait][nng_cv_wait],
+[nng_cv_wake][nng_cv_wake],
+[nng_mtx_alloc][nng_mtx_alloc],
+[nng_mtx_lock][nng_mtx_lock],
+[nng_mtx_unlock][nng_mtx_unlock]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/thr/nng_mtx_alloc.md b/docs/reference/src/thr/nng_mtx_alloc.md
new file mode 100644
index 00000000..c4c38562
--- /dev/null
+++ b/docs/reference/src/thr/nng_mtx_alloc.md
@@ -0,0 +1,46 @@
+# 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 {{i: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],
+[nng_mtx_free][nng_mtx_free],
+[nng_mtx_lock][nng_mtx_lock],
+[nng_mtx_unlock][nng_mtx_unlock]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/thr/nng_mtx_free.md b/docs/reference/src/thr/nng_mtx_free.md
new file mode 100644
index 00000000..ac759331
--- /dev/null
+++ b/docs/reference/src/thr/nng_mtx_free.md
@@ -0,0 +1,25 @@
+# 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)
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/thr/nng_mtx_lock.md b/docs/reference/src/thr/nng_mtx_lock.md
new file mode 100644
index 00000000..be84afe8
--- /dev/null
+++ b/docs/reference/src/thr/nng_mtx_lock.md
@@ -0,0 +1,40 @@
+# 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].
+
+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],
+[nng_mtx_alloc][nng_mtx_alloc],
+[nng_mtx_unlock][nng_mtx_unlock]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/thr/nng_mtx_unlock.md b/docs/reference/src/thr/nng_mtx_unlock.md
new file mode 100644
index 00000000..60fe2f4f
--- /dev/null
+++ b/docs/reference/src/thr/nng_mtx_unlock.md
@@ -0,0 +1,31 @@
+# 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].
+
+> [!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)
+
+{{#include ../refs.md}}