Remove old idmap and mutex docs

6 files changed, 5 insertions, 314 deletions

diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 8b893cae..89546f48 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -286,12 +286,12 @@ as a convenience to aid in creating portable applications.
 |xref:nng_cv_wait.3supp.adoc[nng_cv_wait()]|wait for condition
 |xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters
 |xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter
-|xref:nng_id_map.3supp.adoc[nng_id_map]|identifier based mapping table
+// |xref:nng_id_map.3supp.adoc[nng_id_map]|identifier based mapping table
 |xref:nng_msleep.3supp.adoc[nng_msleep()]|sleep for milliseconds
-|xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc()]|allocate mutex
-|xref:nng_mtx_free.3supp.adoc[nng_mtx_free()]|free mutex
-|xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock()]|lock mutex
-|xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex
+// |xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc()]|allocate mutex
+// |xref:nng_mtx_free.3supp.adoc[nng_mtx_free()]|free mutex
+// |xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock()]|lock mutex
+// |xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex
 |xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options
 |xref:nng_random.3supp.adoc[nng_random()]|get random number
 |xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets
diff --git a/docs/man/nng_id_map.3supp.adoc b/docs/man/nng_id_map.3supp.adoc
deleted file mode 100644
index 5bebf1c4..00000000
--- a/docs/man/nng_id_map.3supp.adoc
+++ /dev/null
@@ -1,108 +0,0 @@
-= nng_id_map(3supp)
-//
-// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
-//
-// 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_id_map - identifier based mapping table
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-#include <nng/supplemental/util/idhash.h>
-
-typedef struct nng_id_map_s nng_id_map;
-
-#define NNG_MAP_RANDOM 1
-
-int   nng_id_map_alloc(nng_id_map **map_p, uint64_t lo, uint64_t hi, int flags);
-void  nng_id_map_free(nng_id_map *map);
-void *nng_id_get(nng_id_map *map, uint64_t id);
-int   nng_id_set(nng_id_map *map, uint64_t, void *value);
-int   nng_id_alloc(nng_id_map *map, uint64_t *id_p, void *value);
-int   nng_id_remove(nng_id_map *map, uint64_t id);
-bool  nng_id_visit(nng_id_map *map, uint64_t *id_p, void **value_p, uint32_t *cursor);
-
-----
-
-== DESCRIPTION
-
-These functions provide support for managing tables of data based on
-identifiers, ensuring that identifiers are allocated uniquely and within
-specified range limits.
-
-The table stores data pointers (which must not be `NULL`) at a logical numeric index.
-It does so efficiently, even if large gaps exist, and it provides a means to efficiently
-allocate a numeric identifier from a pool of unused identifiers.
-
-Identifiers are allocated in increasing order, without reusing old identifiers until the
-largest possible identifier is allocated.  After wrapping, only identifiers that are no longer
-in use will be considered.
-No effort to order the availability of identifiers based on when they were freed is made.
-
-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.
-
-****
-As a special convenience, if these are specified as zero, then a full range of 32-bit identifiers is assumed.
-If identifiers larger than or equal to 2^32^ are required, then both _lo_ and _hi_ must be specified with the
-exact values desired.
-****
-
-The _flags_ argument is a bit mask of flags for the table.
-If `NNG_MAP_RANDOM` is specified, then the starting point for allocations is randomized, but subsequent allocations will then be monotonically increasing.
-This is useful to reduce the odds of different instances of an application using the same identifiers at the same time.
-
-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.
-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 supplied _value_.
-
-The `nng_id_remove()` function removes the identifier and its associated value from 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.
-When all items have been iterated, the function returns `false`.
-The order of items returned is not guaranteed to be sequential.
-The caller must not attempt to derive any value of the _cursor_ as it refers to internal table indices.
-
-NOTE: These functions are limited to storing at most 2^32^ identifiers, even though the identifers may
-themselves be larger than 2^32^.
-
-IMPORTANT: These functions are *not* thread-safe.
-Callers should use a xref:nng_mtx_lock.3supp[mutex] or similar approach when thread-safety is needed.
-
-== RETURN VALUES
-
-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.
-
-== ERRORS
-
-[horizontal]
-`NNG_ENOENT`:: The _id_ does not exist in the table.
-`NNG_ENOMEM`:: Insufficient memory is available, or the table is full.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_mtx_lock.3supp.adoc[nng(7)]
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_mtx_alloc.3supp.adoc b/docs/man/nng_mtx_alloc.3supp.adoc
deleted file mode 100644
index 68ce691b..00000000
--- a/docs/man/nng_mtx_alloc.3supp.adoc
+++ /dev/null
@@ -1,57 +0,0 @@
-= nng_mtx_alloc(3supp)
-//
-// Copyright 2024 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>
-
-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 f247cbf9..00000000
--- a/docs/man/nng_mtx_free.3supp.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-= nng_mtx_free(3supp)
-//
-// Copyright 2024 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>
-
-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 5f4276fc..00000000
--- a/docs/man/nng_mtx_lock.3supp.adoc
+++ /dev/null
@@ -1,55 +0,0 @@
-= nng_mtx_lock(3supp)
-//
-// Copyright 2024 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>
-
-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.
-
-== 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 1752fcf7..00000000
--- a/docs/man/nng_mtx_unlock.3supp.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-= nng_mtx_unlock(3supp)
-//
-// Copyright 2024 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>
-
-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)]