diff options
author | jkoshy <jkoshy@FreeBSD.org> | 2004-10-12 02:36:24 +0000 |
---|---|---|
committer | jkoshy <jkoshy@FreeBSD.org> | 2004-10-12 02:36:24 +0000 |
commit | 9b22f35761e9e6886be441437588d107883bf1e6 (patch) | |
tree | 7d77249c41e13b14461e2891899a7c553489a298 /share/man/man9/hashinit.9 | |
parent | 50bf852114c67dfa79cb0302df4bccd1d7c9078b (diff) | |
download | FreeBSD-src-9b22f35761e9e6886be441437588d107883bf1e6.zip FreeBSD-src-9b22f35761e9e6886be441437588d107883bf1e6.tar.gz |
Add a manual page for hashinit(9), hashdestroy(9) and phashinit(9).
Reviewed by: ru
Diffstat (limited to 'share/man/man9/hashinit.9')
-rw-r--r-- | share/man/man9/hashinit.9 | 150 |
1 files changed, 150 insertions, 0 deletions
diff --git a/share/man/man9/hashinit.9 b/share/man/man9/hashinit.9 new file mode 100644 index 0000000..3d2c996 --- /dev/null +++ b/share/man/man9/hashinit.9 @@ -0,0 +1,150 @@ +.\" +.\" 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 , 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 +.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 +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 . +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. +.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 IMPLEMENTATION NOTES +The largest prime hash value chosen by +.Fn phashinit +is 32749. +.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 SEE ALSO +.Xr LIST_HEAD 3 , +.Xr malloc 9 +.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 BUGS +There is no +.Fn phashdestroy +function, and using +.Fn hashdestroy +to free a hash table allocated by +.Fn phashinit +usually has grave consequences. |