2 .\" Copyright (c) 2004 Joseph Koshy
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
15 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
16 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
17 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE
18 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
19 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
20 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
21 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
22 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
23 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
24 .\" POSSIBILITY OF SUCH DAMAGE.
32 .Nm hashinit , hashdestroy , phashinit
33 .Nd manage kernel hash tables
39 .Fn hashinit "int nelements" "struct malloc_type *type" "u_long *hashmask"
41 .Fn hashdestroy "void *hashtbl" "struct malloc_type *type" "u_long hashmask"
43 .Fn phashinit "int nelements" "struct malloc_type *type" "u_long *nentries"
49 functions allocate space for hash tables of size given by the argument
54 function allocates hash tables that are sized to largest power of two
55 less than or equal to argument
59 function allocates hash tables that are sized to the largest prime
60 number less than or equal to argument
62 Allocated hash tables are contiguous arrays of
64 entries, allocated using
68 The malloc arena to be used for allocation is pointed to by argument
73 function frees the space occupied by the hash table pointed to by argument
77 determines the malloc arena to use when freeing space.
80 should be the bit mask returned by the call to
82 that allocated the hash table.
83 .Sh IMPLEMENTATION NOTES
84 The largest prime hash value chosen by
90 function returns a pointer to an allocated hash table and sets the
91 location pointed to by
93 to the bit mask to be used for computing the correct slot in the
98 function returns a pointer to an allocated hash table and sets the
99 location pointed to by
101 to the number of rows in the hash table.
103 A typical example is shown below:
104 .Bd -literal -offset indent
106 static LIST_HEAD(foo, foo) *footable;
107 static u_long foomask;
109 footable = hashinit(32, M_FOO, &foomask);
112 Here we allocate a hash table with 32 entries from the malloc arena
115 The mask for the allocated hash table is returned in
121 .Bd -literal -offset indent
123 hashdestroy(footable, M_FOO, foomask);
130 functions will panic if argument
132 is less than or equal to zero.
136 function will panic if the hash table
148 to free a hash table allocated by
150 usually has grave consequences.