hashinit (9)

Leading comments

Copyright (c) 2004 Joseph Koshy
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other...

(The comments found at the beginning of the groff file "man9/hashinit.9freebsd".)

NAME

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

SYNOPSIS

In sys/malloc.h In sys/systm.h In sys/queue.h Ft void * Fn hashinit int nelements struct malloc_type *type u_long *hashmask Ft void Fo hashinit_flags Fa int nelements struct malloc_type *type u_long *hashmask int flags Fc Ft void Fn hashdestroy void *hashtbl struct malloc_type *type u_long hashmask Ft void * Fn phashinit int nelements struct malloc_type *type u_long *nentries

DESCRIPTION

The Fn hashinit , Fn hashinit_flags and Fn phashinit functions allocate space for hash tables of size given by the argument Fa nelements .

The Fn hashinit function allocates hash tables that are sized to largest power of two less than or equal to argument Fa nelements . The Fn phashinit function allocates hash tables that are sized to the largest prime number less than or equal to argument Fa nelements . The Fn hashinit_flags function operates like Fn hashinit but also accepts an additional argument Fa flags which control various options during allocation. Allocated hash tables are contiguous arrays of LIST_HEAD3 entries, allocated using malloc(9), and initialized using LIST_INIT3. The malloc arena to be used for allocation is pointed to by argument Fa type .

The Fn hashdestroy function frees the space occupied by the hash table pointed to by argument Fa hashtbl . Argument Fa type determines the malloc arena to use when freeing space. The argument Fa hashmask should be the bit mask returned by the call to Fn hashinit that allocated the hash table. The argument Fa flags must be used with one of the following values.

HASH_NOWAIT

Any malloc performed by the Fn hashinit_flags function will not be allowed to wait, and therefore may fail.

HASH_WAITOK

Any malloc performed by the Fn hashinit_flags function is allowed to wait for memory.

IMPLEMENTATION NOTES

The largest prime hash value chosen by Fn phashinit is 32749.

RETURN VALUES

The Fn hashinit function returns a pointer to an allocated hash table and sets the location pointed to by Fa hashmask to the bit mask to be used for computing the correct slot in the hash table.

The Fn phashinit function returns a pointer to an allocated hash table and sets the location pointed to by Fa 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 Fn hashdestroy uses the value in foomask

...
hashdestroy(footable, M_FOO, foomask);

DIAGNOSTICS

The Fn hashinit and Fn phashinit functions will panic if argument Fa nelements is less than or equal to zero.

The Fn hashdestroy function will panic if the hash table pointed to by Fa hashtbl is not empty.

SEE ALSO

LIST_HEAD3, malloc(9)

BUGS

There is no Fn phashdestroy function, and using Fn hashdestroy to free a hash table allocated by Fn phashinit usually has grave consequences.