Add nng_mtx_* functions.

6 files changed, 151 insertions, 12 deletions

diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md
index 0a99d045..98d70ad7 100644
--- a/docs/reference/src/SUMMARY.md
+++ b/docs/reference/src/SUMMARY.md
@@ -111,6 +111,10 @@
     - [nng_cv_wait](api/threads/nng_cv_wait.md)
     - [nng_cv_wake](api/threads/nng_cv_wake.md)
     - [nng_cv_wake1](api/threads/nng_cv_wake1.md)
+    - [nng_mtx_alloc](api/threads/nng_mtx_alloc.md)
+    - [nng_mtx_free](api/threads/nng_mtx_free.md)
+    - [nng_mtx_lock](api/threads/nng_mtx_lock.md)
+    - [nng_mtx_unlock](api/threads/nng_mtx_unlock.md)
 
   - [Legacy Compatibility](api/compat/index.md)
 
diff --git a/docs/reference/src/api/msg/index.md b/docs/reference/src/api/msg/index.md
index 1a7bdabf..54d8d9b8 100644
--- a/docs/reference/src/api/msg/index.md
+++ b/docs/reference/src/api/msg/index.md
@@ -48,25 +48,26 @@ that would affect the binary representation of the `nng_msg` itself.
 ### Example 1: Preparing a message for use
 
 ```c
-#include <nng/nng.h>
-nng_msg *m;
-if (nng_msg_alloc(&m, strlen("content") + 1) != 0) {
-   // handle error
-}
-strcpy(nng_msg_body(m), "content");
+    #include <nng/nng.h>
+
+    nng_msg *m;
+    if (nng_msg_alloc(&m, strlen("content") + 1) != 0) {
+       // handle error
+    }
+    strcpy(nng_msg_body(m), "content");
 ```
 
 ### Example 2: Preallocating message content
 
 ```c
-if (nng_msg_alloc(&m, 1024) != 0) {
-    // handle error
-}
-while ((val64 = next_datum()) != 0) P
-    if (nng_msg_append_u64(m, val64) != 0) {
+    if (nng_msg_alloc(&m, 1024) != 0) {
         // handle error
     }
-}
+    while ((val64 = next_datum()) != 0) P
+        if (nng_msg_append_u64(m, val64) != 0) {
+            // handle error
+        }
+    }
 ```
 
 ## See Also
diff --git a/docs/reference/src/api/threads/nng_mtx_alloc.md b/docs/reference/src/api/threads/nng_mtx_alloc.md
new file mode 100644
index 00000000..64263d59
--- /dev/null
+++ b/docs/reference/src/api/threads/nng_mtx_alloc.md
@@ -0,0 +1,44 @@
+# 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
new file mode 100644
index 00000000..a6fe7d7b
--- /dev/null
+++ b/docs/reference/src/api/threads/nng_mtx_free.md
@@ -0,0 +1,23 @@
+# 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
new file mode 100644
index 00000000..2e50f010
--- /dev/null
+++ b/docs/reference/src/api/threads/nng_mtx_lock.md
@@ -0,0 +1,38 @@
+# 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
new file mode 100644
index 00000000..d5815287
--- /dev/null
+++ b/docs/reference/src/api/threads/nng_mtx_unlock.md
@@ -0,0 +1,29 @@
+# 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)