This documentation is for the TIP (development tree) of NNG and may represent unreleased changes or functionality that is experimental, and is subject to change before release. The latest released version is v1.8.0. See the documentation for v1.8.0 for the most up-to-date information.

nng_id_map(3supp)

NAME

nng_id_map - identifier based mapping table

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);

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³² 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.

These functions are limited to storing at most 2³² identifiers, even though the identifers may themselves be larger than 2³².

These functions are not thread-safe. Callers should use a 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.