FreeBSD Manual Pages

HASHINIT(9) FreeBSD Kernel Developer's Manual HASHINIT(9)
NAMEhashinit, hashinit_flags, hashdestroy, phashinit -- manage kernel hash
tables
SYNOPSIS#include <sys/malloc.h>
#include <sys/systm.h>
#include <sys/queue.h>
void*hashinit(intnelements, structmalloc_type*type, u_long*hashmask);
voidhashinit_flags(intnelements, structmalloc_type*type, u_long*hashmask,
intflags);
voidhashdestroy(void*hashtbl, structmalloc_type*type, u_longhashmask);
void*phashinit(intnelements, structmalloc_type*type, u_long*nentries);
DESCRIPTION
The hashinit(), hashinit_flags() and phashinit() functions allocate space
for hash tables of size given by the argument nelements.
The hashinit() function allocates hash tables that are sized to largest
power of two less than or equal to argument nelements. The phashinit()
function allocates hash tables that are sized to the largest prime number
less than or equal to argument nelements. The hashinit_flags() function
operates like hashinit() but also accepts an additional argument flags
which control various options during allocation. Allocated hash tables
are contiguous arrays of LIST_HEAD(3) entries, allocated using malloc(9),
and initialized using LIST_INIT(3). The malloc arena to be used for
allocation is pointed to by argument type.
The hashdestroy() function frees the space occupied by the hash table
pointed to by argument hashtbl. Argument type determines the malloc
arena to use when freeing space. The argument hashmask should be the bit
mask returned by the call to hashinit() that allocated the hash table.
The argument flags must be used with one of the following values.
HASH_NOWAIT Any malloc performed by the hashinit_flags() function
will not be allowed to wait, and therefore may fail.
HASH_WAITOK Any malloc performed by the hashinit_flags() function
is allowed to wait for memory.
IMPLEMENTATION NOTES
The largest prime hash value chosen by phashinit() is 32749.
RETURN VALUES
The hashinit() function returns a pointer to an allocated hash table and
sets the location pointed to by hashmask to the bit mask to be used for
computing the correct slot in the hash table.
The phashinit() function returns a pointer to an allocated hash table and
sets the location pointed to by nentries to the number of rows in the
hash table.
EXAMPLES
A typical example is shown below:
...
static LIST_HEAD(foo, foo) *footable;
static u_long foomask;
...
footable = hashinit(32, M_FOO, &foomask);
Here we allocate a hash table with 32 entries from the malloc arena
pointed to by M_FOO. The mask for the allocated hash table is returned
in foomask. A subsequent call to hashdestroy() uses the value in
foomask:
...
hashdestroy(footable, M_FOO, foomask);
DIAGNOSTICS
The hashinit() and phashinit() functions will panic if argument nelements
is less than or equal to zero.
The hashdestroy() function will panic if the hash table pointed to by
hashtbl is not empty.
SEE ALSOLIST_HEAD(3), malloc(9)BUGS
There is no phashdestroy() function, and using hashdestroy() to free a
hash table allocated by phashinit() usually has grave consequences.
FreeBSD 11.1 October 10, 2004 FreeBSD 11.1