177 lines
4.7 KiB
Groff
177 lines
4.7 KiB
Groff
.\"
|
|
.\" 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 materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
|
|
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE
|
|
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd October 10, 2004
|
|
.Dt HASHINIT 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm hashinit , hashinit_flags, hashdestroy , phashinit
|
|
.Nd manage kernel hash tables
|
|
.Sh 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"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn hashinit ,
|
|
.Fn hashinit_flags
|
|
and
|
|
.Fn phashinit
|
|
functions allocate space for hash tables of size given by the argument
|
|
.Fa nelements .
|
|
.Pp
|
|
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
|
|
.Xr LIST_HEAD 3
|
|
entries, allocated using
|
|
.Xr malloc 9 ,
|
|
and initialized using
|
|
.Xr LIST_INIT 3 .
|
|
The malloc arena to be used for allocation is pointed to by argument
|
|
.Fa type .
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.Bl -tag -width ".Dv HASH_NOWAIT" -offset indent -compact
|
|
.It Dv HASH_NOWAIT
|
|
Any malloc performed by the
|
|
.Fn hashinit_flags
|
|
function will not be allowed to wait, and therefore may fail.
|
|
.It Dv HASH_WAITOK
|
|
Any malloc performed by the
|
|
.Fn hashinit_flags
|
|
function is allowed to wait for memory.
|
|
.El
|
|
.Sh IMPLEMENTATION NOTES
|
|
The largest prime hash value chosen by
|
|
.Fn phashinit
|
|
is 32749.
|
|
.Sh 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.
|
|
.Pp
|
|
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.
|
|
.Sh EXAMPLES
|
|
A typical example is shown below:
|
|
.Bd -literal -offset indent
|
|
\&...
|
|
static LIST_HEAD(foo, foo) *footable;
|
|
static u_long foomask;
|
|
\&...
|
|
footable = hashinit(32, M_FOO, &foomask);
|
|
.Ed
|
|
.Pp
|
|
Here we allocate a hash table with 32 entries from the malloc arena
|
|
pointed to by
|
|
.Dv M_FOO .
|
|
The mask for the allocated hash table is returned in
|
|
.Va foomask .
|
|
A subsequent call to
|
|
.Fn hashdestroy
|
|
uses the value in
|
|
.Va foomask :
|
|
.Bd -literal -offset indent
|
|
\&...
|
|
hashdestroy(footable, M_FOO, foomask);
|
|
.Ed
|
|
.Sh DIAGNOSTICS
|
|
The
|
|
.Fn hashinit
|
|
and
|
|
.Fn phashinit
|
|
functions will panic if argument
|
|
.Fa nelements
|
|
is less than or equal to zero.
|
|
.Pp
|
|
The
|
|
.Fn hashdestroy
|
|
function will panic if the hash table
|
|
pointed to by
|
|
.Fa hashtbl
|
|
is not empty.
|
|
.Sh SEE ALSO
|
|
.Xr LIST_HEAD 3 ,
|
|
.Xr malloc 9
|
|
.Sh BUGS
|
|
There is no
|
|
.Fn phashdestroy
|
|
function, and using
|
|
.Fn hashdestroy
|
|
to free a hash table allocated by
|
|
.Fn phashinit
|
|
usually has grave consequences.
|