From d3652db599cb3bf4101cf2e6cf42c764d65b6fb8 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Sun, 11 Aug 2024 22:12:30 -0700
Subject: idhash: add nng_id_visit API

This allows an efficient way to iterate over the entries
stored in an ID hash. The iteration is fast, and requires no
additional storage.  The order of iteration is not guaranteed.
---
 docs/man/nng_id_map.3supp.adoc | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'docs/man/nng_id_map.3supp.adoc')

diff --git a/docs/man/nng_id_map.3supp.adoc b/docs/man/nng_id_map.3supp.adoc
index 343c0667..5bebf1c4 100644
--- a/docs/man/nng_id_map.3supp.adoc
+++ b/docs/man/nng_id_map.3supp.adoc
@@ -29,6 +29,7 @@ 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);
 
 ----
 
@@ -74,6 +75,13 @@ 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^.
 
-- 
cgit v1.2.3-70-g09d2

