NNG_ID_MAP(3supp)

okay bestie, this is NNG_ID_MAP(3supp) from the NNG Reference Manual — the whole page is about an identifier-based mapping table, and it's lowkey iconic. Let's get into it 💖

---

🌸 NAME 🌸

nng_id_map — identifier based mapping table. periodt.

✨ SYNOPSIS ✨

#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 💅

okay so these functions are literally here to help you manage tables of data keyed by identifiers. They make sure identifiers are allocated uniquely and stay inside the specified range limits. No duplicates, no chaos, just vibes.

The table stores data pointers — and bestie, those pointers must not be NULL — at a logical numeric index. It does this efficiently even if there are huge gaps, and it gives you a way to efficiently allocate a numeric identifier from a pool of unused identifiers. It's giving organized.

Identifiers are allocated in increasing order, and old identifiers are not reused 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. So yeah, it's not doing extra credit there.

You start by allocating an initial table with nng_id_map_alloc(). It takes the lowest legal identifier in lo and the largest legal identifier in hi. The new table comes back in map_p, and you should use that as the map argument to the rest of these functions. slay.

✨ Special convenience alert: if lo and hi are specified as zero, then a full range of 32-bit identifiers is assumed. If you need identifiers greater than or equal to 2^32, then both lo and hi must be specified with the exact values you want. No guessing, bestie.

The flags argument is a bit mask of flags for the table.

• NNG_MAP_RANDOM — if this is specified, 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. Cute and practical 💅

The nng_id_get() function returns the value previously stored with the given identifier. If no value is currently associated with that identifier, it returns NULL. No value, no pointer.

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. Heads up though: this function does not necessarily honor the identifier range limits set for the map when it was allocated. So yeah, it can be a little rebellious.

The nng_id_alloc() function allocates a new identifier from the range for the map and associates it with the supplied value. fresh id, who dis.

The nng_id_remove() function removes the identifier and its associated value from the table. bye bye.

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, because it refers to internal table indices. Do not try to make fetch happen with that cursor, okay?

🦋 Note: These functions are limited to storing at most 2^32 identifiers, even though the identifiers themselves may be larger than 2^32. respect the limit.

🚨 Important: These functions are not thread-safe. Callers should use a mutex or similar approach when thread-safety is needed. Protect your peace and your shared state, bestie.

🔥 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. success vibes or fail vibes.

The nng_id_map_get() function returns the requested data pointer, or NULL if the identifier was not found. simple.

💀 ERRORS 💀

• NNG_ENOENT — the id does not exist in the table. It's giving missing.
• NNG_ENOMEM — insufficient memory is available, or the table is full. No room, no vibes.

🫶 SEE ALSO 🫶

nng(7) nng(7) — yes, it's listed twice, and we are respecting the duplication 💖

---

mwah 💋 — that's the whole NNG_ID_MAP(3supp) page from the NNG Reference Manual, dated 2026-01-13. You ate, bestie. 💅✨