=encoding utf8

=head1 NAME

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

=head1 SYNOPSIS

B<#include E<lt>critnib.hE<gt>>

Link with I<-lcritnib>.

=head1 DESCRIPTION

=head2 Functions:

=over

=item B<critnib *critnib_new(void);>

Creates a new empty critnib structure.

=item B<void critnib_delete(critnib *>I<c>B<);>

Destroys and frees the memory.  Note that removed items are reused but won't
have their memory freed until this function is called.

=item B<int critnib_insert(critnib *>I<c>B<, uintptr_t >I<key>B<, void *>I<value>B<, int >I<update>B<);>

Adds a key:value pair to the critnib structure.  If I<update> is non-zero,
an already existing key has its value updated, otherwise the function returns
B<EEXIST>.  It may return B<ENOMEM> if we're out of memory, or 0 if all went
okay.

=item B<void *critnib_remove(critnib *>I<c>B<, uintptr_t >I<key>B<);>

Removes a given key from the structure.  Its associated value is returned,
or 0 (NULL) if there was no such key.

=item B<void *critnib_get(critnib *>I<c>B<, uintptr_t >I<key>B<);>

Obtains a value for a given key, or 0 (NULL) if not present.

=item B<void *critnib_find_le(critnib *>I<c>B<, uintptr_t >I<key>B<);>

Searches for the largest key not exceeding the argument, and returns its value.

=item B<int critnib_find(critnib *>I<c>B<, uintptr_t >I<key>B<, enum find_dir_t >I<dir>B<, uintptr_t *>I<rkey>B<, void **>I<rvalue>B<);>

Searches for a key that's smaller (B<FIND_L>), smaller-or-equal (B<FIND_LE>),
equal (B<FIND_EQ>), greater-or-equal (B<FIND_GE>), or greater (B<FIND_G>) than
the argument.  If found, the key and value are assigned to I<*rkey> and I<*rvalue>
(which may be null to skip assignment), and 1 is returned.

=item B<void critnib_iter(critnib *>I<c>B<, uintptr_t >I<min>B<, uintptr_t >I<max>B<, >I<func>B<, void *>I<privdata>B<);>

Walks the structure, visiting all entries whose keys are at least I<min> but
no larger than I<max> (give B<-1> for no max), calling I<func> for every
entry found.  If the I<func> returns a non-zero value, the walk is aborted.

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

B<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.>

=back
