Docs for mutexes converted.

docs/ref/SUMMARY.md

@@ -1,7 +1,9 @@
 # Summary
 
 - [API](./api.md)
-  - [Utility Functions](./api/util.md)
+  - [Threading Functions](./api/thr/index.md)
+    - [nng_mtx](./api/thr/nng_mtx.md)
+  - [Utility Functions](./api/util/index.md)
     - [nng_id_map](./api/util/nng_id_map.md)
 
 [Index](./indexing.md)

docs/ref/api.md

@@ -1 +1,4 @@
 # API
+
+- [Threading Support](api/thr/)
+- [Utility Functions](api/util/)

docs/ref/api/thr/index.md

@@ -0,0 +1,3 @@
+# Threading Functions
+
+- [nng_mtx](nng_mtx.md)

docs/ref/api/thr/nng_mtx.md

@@ -0,0 +1,63 @@
+# nng_id_map
+
+## NAME
+
+nng_mutex - mutual exclusion lock
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+typedef struct nng_mtx nng_mtx;
+
+int nng_mtx_alloc(nng_mtx **mtxp);
+void nng_mtx_free(nng_mtx *mtx);
+void nng_mtx_lock(nng_mtx *mtx);
+void nng_mtx_unlock(nng_mtx *mtx);
+```
+
+## DESCRIPTION
+
+The {{i:`nng_mutex`}}{{hi:mutex}} structure provides a {{i:mutual-exclusion}} {{i:lock}}, such
+that only one thread at a time can have the lock (taken using `nng_mtx_lock`).
+This is critical for solving certain problems that arise in concurrent programming.
+
+### Initialization and Teardown
+
+The `nng_mtx` structure is created dynamically, by the application using `nng_mtx_alloc`.
+This function will store a pointer to the allocate mutex at the location signified by _mtxp_.
+
+When the application has no further need of the mutex, it can deallocate the resources
+associated using the `nng_mtx_free` function.
+
+### Locking and Unlocking
+
+The `nng_mtx` lock can be acquired by a calling thread using the `nng_mtx_lock` function.
+
+The caller will block until the lock is acquired.
+If multiple threads are contending for ownership of the lock, the order of
+acquisition is not specified, and applications must not depend on 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.
+
+The lock can be released by the thread that has ownership using the `nng_mtx_unlock` function.
+
+> [!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.
+
+## RETURN VALUES
+
+The `nng_mtx_lock` function returns 0 on success, or non-zero on failure.
+
+The other mutex functions always succeed, and have no return values.
+
+## ERRORS
+
+- `NNG_ENOMEM`: Insufficient memory is available, or the table is full.

docs/ref/api/util/index.md

@@ -0,0 +1,3 @@
+# Utility Functions
+
+- [nng_id_map](nng_id_map.md)

docs/ref/api/util/nng_id_map.md

@@ -47,7 +47,7 @@ Given a sufficiently large range, this is unlikely to be a concern.}}
 
 ### Initialization
 
-An initial table is allocated with `nng_id_map_alloc()`, which takes the lowest legal identifier in _lo_,
+An initial table is allocated with `nng_id_map_alloc`, which takes the lowest legal identifier in _lo_,
 and the largest legal identifier in _hi_.
 The new table is returned in _map_p_, and should be used as the _map_ argument to the rest of these functions.
 
@@ -63,22 +63,22 @@ This is useful to reduce the odds of different instances of an application using
 
 ### Accessors
 
-The `nng_id_get()` function returns the value previously stored with the given identifier.
+The `nng_id_get` function returns the value previously stored with the given identifier.
 If no value is currently associated with the identifer, it returns `NULL`.
 
-The `nng_id_set()` function sets the value with the associated identifier.
+The `nng_id_set` function sets the value with the associated identifier.
 This can be used to replace a previously allocated identifier.
 If the identifier was not previously allocated, then it is allocated as part of the call.
 This function does not necessarily honor the identifier range limits set for the map when it was allocated.
 
-The `nng_id_alloc()` function allocates a new identifier from the range for the map, and associates it with
+The `nng_id_alloc` function allocates a new identifier from the range for the map, and associates it with
 the supplied _value_.
 
-The `nng_id_remove()` function removes the identifier and its associated value from the table.
+The `nng_id_remove` function removes the identifier and its associated value from the table.
 
 ### Iteration
 
-The `nng_id_visit()` function is used to iterate over all items in the table.
+The `nng_id_visit` function is used to iterate over all items in the table.
 The caller starts the iteration by setting the _cursor_ to 0 before calling it.
 For each call, the associated key and value of the next item will be returned in _id_p_,
 and _value_p_ and the _cursor_ will be updated.
@@ -88,14 +88,14 @@ The caller must not attempt to derive any value of the _cursor_ as it refers to
 
 ## RETURN VALUES
 
-The `nng_id_map_alloc()`, `nng_id_set()`, `nng_id_alloc()`, and `nng_id_remove()` functions
+The `nng_id_map_alloc`, `nng_id_set`, `nng_id_alloc`, and `nng_id_remove` functions
 return 0 on success, or -1 on failure.
 
-The `nng_id_map_get()` function returns the requested data pointer, or `NULL` if the identifier was not found.
+The `nng_id_map_get` function returns the requested data pointer, or `NULL` if the identifier was not found.
 
 ## ERRORS
 
 - `NNG_ENOENT`: The _id_ does not exist in the table.
 - `NNG_ENOMEM`: Insufficient memory is available, or the table is full.
 
-[mutex]: ../thr/mutex.md
+[mutex]: ../thr/nng_mtx.md