id_map converted

3 files changed, 94 insertions, 0 deletions

diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md
index e8d40df8..42910b17 100644
--- a/docs/reference/src/SUMMARY.md
+++ b/docs/reference/src/SUMMARY.md
@@ -111,6 +111,7 @@
     - [nng_alloc](util/nng_alloc.md)
     - [nng_clock](util/nng_clock.md)
     - [nng_free](util/nng_free.md)
+    - [nng_id_map](util/nng_id_map.md)
     - [nng_msleep](util/nng_msleep.md)
     - [nng_random](util/nng_random.md)
     - [nng_sleep_aio](util/nng_sleep_aio.md)
diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md
index 43e9b435..2c7e5028 100644
--- a/docs/reference/src/refs.md
+++ b/docs/reference/src/refs.md
@@ -137,6 +137,7 @@
 [nng_alloc]: ../util/nng_alloc.md
 [nng_clock]: ../util/nng_clock.md
 [nng_free]: ../util/nng_free.md
+[nng_id_map]: ../util/nng_id_map.md
 [nng_msleep]: ../util/nng_msleep.md
 [nng_random]: ../util/nng_random.md
 [nng_sleep_aio]: ../util/nng_sleep_aio.md
diff --git a/docs/reference/src/util/nng_id_map.md b/docs/reference/src/util/nng_id_map.md
new file mode 100644
index 00000000..2e7f63af
--- /dev/null
+++ b/docs/reference/src/util/nng_id_map.md
@@ -0,0 +1,92 @@
+# nng_id_map
+
+## NAME
+
+nng_id_map --- identifier based mapping table
+
+## SYNOPSIS
+
+```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);
+```
+
+## DESCRIPTION
+
+These functions provide support for managing tables of data based on
+{{i: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 is made to order the availability of identifiers based on when they were freed.[^1]
+
+[^1]:
+    The concern about possibly reusing a recently released identifier
+    comes into consideration after the range has wrapped. Given a sufficiently
+    large range, this is unlikely to be a concern.
+
+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.
+
+If these _lo_ and _hi_ are both zero, then a full range of 32-bit identifiers is assumed.[^2]
+
+[^2]:
+    Consequently, if identifiers larger than or equal to 2<sup>32</sup> 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 {{i:`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.
+
+> [!NOTE]
+> These functions are limited to storing at most 2<sup>32</sup> used identifiers, even though the identifers may
+> themselves be larger than 2<sup>32</sup>.
+
+> [!NOTE]
+> These functions are _not_ thread-safe.
+> Callers should use a [mutex][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
+
+- `NNG_ENOENT`: The _id_ does not exist in the table.
+- `NNG_ENOMEM`: Insufficient memory is available, or the table is full.
+
+{{#include ../refs.md}}