NAME

       libcritnib - an ordered map data structure with lock-free reads

SYNOPSIS

       #include <critnib.h>

       Link with -lcritnib.

DESCRIPTION

   Functions:
       critnib *critnib_new(void);
           Creates a new empty critnib structure.

       void critnib_delete(critnib *c);
           Destroys and frees the memory.  Note that removed items are reused but won't have
           their memory freed until this function is called.

       int critnib_insert(critnib *c, uintptr_t key, void *value, int update);
           Adds a key:value pair to the critnib structure.  If update is non-zero, an already
           existing key has its value updated, otherwise the function returns EEXIST.  It may
           return ENOMEM if we're out of memory, or 0 if all went okay.

       void *critnib_remove(critnib *c, uintptr_t key);
           Removes a given key from the structure.  Its associated value is returned, or 0 (NULL)
           if there was no such key.

       void *critnib_get(critnib *c, uintptr_t key);
           Obtains a value for a given key, or 0 (NULL) if not present.

       void *critnib_find_le(critnib *c, uintptr_t key);
           Searches for the largest key not exceeding the argument, and returns its value.

       int critnib_find(critnib *c, uintptr_t key, enum find_dir_t dir, uintptr_t *rkey, void
       **rvalue);
           Searches for a key that's smaller (FIND_L), smaller-or-equal (FIND_LE), equal
           (FIND_EQ), greater-or-equal (FIND_GE), or greater (FIND_G) than the argument.  If
           found, the key and value are assigned to *rkey and *rvalue (which may be null to skip
           assignment), and 1 is returned.

       void critnib_iter(critnib *c, uintptr_t min, uintptr_t max, func, void *privdata);
           Walks the structure, visiting all entries whose keys are at least min but no larger
           than max (give -1 for no max), calling func for every entry found.  If the func
           returns a non-zero value, the walk is aborted.

           The prototype for func should be: int (*func)(uintptr_t key, void *value, void
           *privdata); where privdata is an optional value passed to the iterator.

           NB. This version of the library implements the iterator in a crude blocking way,
           stalling any concurrent writers and iterators.  This limitation will be lifted in the
           future.