NAME

       hashinit, hashinit_flags, hashdestroy, phashinit — manage kernel hash tables

SYNOPSIS

       #include <sys/malloc.h>
       #include <sys/systm.h>
       #include <sys/queue.h>

       void *
       hashinit(int nelements, struct malloc_type *type, u_long *hashmask);

       void
       hashinit_flags(int nelements, struct malloc_type *type, u_long *hashmask, int flags);

       void
       hashdestroy(void *hashtbl, struct malloc_type *type, u_long hashmask);

       void *
       phashinit(int nelements, struct malloc_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 ALSO

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

Debian                                          October 10, 2004                                     HASHINIT(9)