From c5afb3b3c70c026e8f72674ff6973581055658e7 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Wed, 27 Mar 2024 07:53:26 -0700
Subject: Add nng_mtx_* functions.

---
 docs/reference/src/api/threads/nng_mtx_alloc.md  | 44 ++++++++++++++++++++++++
 docs/reference/src/api/threads/nng_mtx_free.md   | 23 +++++++++++++
 docs/reference/src/api/threads/nng_mtx_lock.md   | 38 ++++++++++++++++++++
 docs/reference/src/api/threads/nng_mtx_unlock.md | 29 ++++++++++++++++
 4 files changed, 134 insertions(+)
 create mode 100644 docs/reference/src/api/threads/nng_mtx_alloc.md
 create mode 100644 docs/reference/src/api/threads/nng_mtx_free.md
 create mode 100644 docs/reference/src/api/threads/nng_mtx_lock.md
 create mode 100644 docs/reference/src/api/threads/nng_mtx_unlock.md

(limited to 'docs/reference/src/api/threads')

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)
-- 
cgit v1.2.3-70-g09d2