Add nng_mtx_* functions.

10 files changed, 151 insertions, 226 deletions

diff --git a/docs/man/nng_mtx_alloc.3supp.adoc b/docs/man/nng_mtx_alloc.3supp.adoc
deleted file mode 100644
index 45bbfac2..00000000
--- a/docs/man/nng_mtx_alloc.3supp.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-= nng_mtx_alloc(3supp)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_mtx_alloc - allocate mutex
-
-== SYNOPSIS
-
-[source, 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
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient free memory exists.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)],
-xref:nng_mtx_free.3supp.adoc[nng_mtx_free(3supp)],
-xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)],
-xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_mtx_free.3supp.adoc b/docs/man/nng_mtx_free.3supp.adoc
deleted file mode 100644
index 2867afe1..00000000
--- a/docs/man/nng_mtx_free.3supp.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-= nng_mtx_free(3supp)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_mtx_free - free mutex
-
-== SYNOPSIS
-
-[source, 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.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_mtx_lock.3supp.adoc b/docs/man/nng_mtx_lock.3supp.adoc
deleted file mode 100644
index 91fd2ab5..00000000
--- a/docs/man/nng_mtx_lock.3supp.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-= nng_mtx_lock(3supp)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_mtx_lock - lock mutex
-
-== SYNOPSIS
-
-[source, 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 xref:nng_mtx_unlock.3supp.adoc[`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.
-
-IMPORTANT: 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.
-
-****
-_NNG_ offers neither a non-blocking variant that can fail,
-nor recursive mutexes.
-This is by design, as _NNG_ itself does not use such things,
-and most often the need for them is the result of poor design.
-If such capabilities are needed, they may be synthesized fairly
-easily from mutexes and condition variables.
-****
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)],
-xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)],
-xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_mtx_unlock.3supp.adoc b/docs/man/nng_mtx_unlock.3supp.adoc
deleted file mode 100644
index d1b048e6..00000000
--- a/docs/man/nng_mtx_unlock.3supp.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-= nng_mtx_unlock(3supp)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_mtx_unlock - unlock mutex
-
-== SYNOPSIS
-
-[source, 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 xref:nng_mtx_lock.3supp.adoc[`nng_mtx_lock()`].
-
-IMPORTANT: 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.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)],
-xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)],
-xref:nng.7.adoc[nng(7)]
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)