NAME

hmap_init, hmap_next, hmap_set, hmap_get, hmap_free - hash table management

SYNOPSIS

#include <limb/hmap.h>

int hmap_init(size_t dlen, size_t n, hmap *hmap)
void *hmap_next(u32 *key, hmap *hmap)
int hmap_set(u32 key, void *data, hmap *hmap)
void *hmap_get(u32 key, hmap *hmap)
void hmap_free(hmap *hmap)

DESCRIPTION

These functions allow the caller to manage a hash table containing entries consisting of a key (a 32bit unsigned integer) and its associated data. The last argument, hmap, points to a structure that describes the table on which the function operates, and should be treated as opaque (i.e. do not attempt to directly access or modify the fields in this structure.).

The size of the associated data are defined by the hmap_init() call, they can therefore be different for each hash table, but are of fixed size on a per-table basis (and cannot be modified).

First, the hmap_init() function must be used to initialize the structure pointed to by hmap for a hash table of n elements, using dlen bytes as per-element data size.

The hash table will automatically grow as needed when adding new elements, but it is not possible to shrunk it down, nor is it possible to remove elements. Note also that the actual size of the table must be a power of two, and will therefore be adjusted accordingly (e.g. using 10 as n will actually result in a table initialized for 16 elements).

The hmap_set() function searches the table for an element with the given key and sets its associated data to that pointed to by data (which must be of the size given as dlen to hmap_init() earlier). Note that the actual data pointed will be copied into the table.

If not such element exists, it is added to the table. If needed the table might grow its size in order to add the new element.

To get a valid 32bit key from a data blob (e.g. a string), you might want to use hlookup32(3).

The hmap_get() function searches the table for an element with the given key and returns a pointer to its associated data when found, or NULL if no such element exists in the table.

The hmap_next() function allows to iterate over all elements in the table, although this is not an optimized path. It will locate the element for the key pointed to by key, set it to the key of the next element and return a pointer to its associated data. If there are no more elements in the table, it will return NULL.

The first call to hmap_next() must have the value pointe by key by zero, successive calls must them re-use the value in order to move forward. Although changing an element's data is allowed, one should not change the table's content during such iteration (i.e. do not add elements to the table).

The hmap_free() function frees all memory allocated by the table and returns it into a uninitialized state. It is then possible to re-use it with hmap_init() with different parameters.

RETURN VALUE

The hmap_init() and hmap_set() functions return 1 on success, and zero on error, with errno set to indicate the cause of the error.

The hmap_get() function returns a pointer to the data associated with the element if found, or NULL otherwise. It cannot fail.

The hmap_next() function returns a pointer to the data associated with the element, or NULL is the table is empty or has been fully iterated (no more elements past the one whose key is pointed to by key). It cannot fail.

ERRORS

The hmap_init() function may fail if :

The hmap_set() function may fail if :