2 * UCW Library -- Universal Hash Table
4 * (c) 2002--2004 Martin Mares <mj@ucw.cz>
5 * (c) 2002--2005 Robert Spalek <robert@ucw.cz>
7 * This software may be freely distributed and used according to the terms
8 * of the GNU Lesser General Public License.
12 * This is not a normal header file, it's a generator of hash tables.
13 * Each time you include it with parameters set in the corresponding
14 * preprocessor macros, it generates a hash table with the parameters
17 * You need to specify:
19 * HASH_NODE data type where a node dwells (usually a struct).
20 * HASH_PREFIX(x) macro to add a name prefix (used on all global names
21 * defined by the hash table generator).
23 * Then decide on type of keys:
25 * HASH_KEY_ATOMIC=f use node->f as a key of an atomic type (i.e.,
26 * a type which can be compared using `==')
27 * HASH_ATOMIC_TYPE (defaults to int).
28 * | HASH_KEY_STRING=f use node->f as a string key, allocated
29 * separately from the rest of the node.
30 * | HASH_KEY_ENDSTRING=f use node->f as a string key, allocated
31 * automatically at the end of the node struct
32 * (to be declared as "char f[1]" at the end).
33 * | HASH_KEY_COMPLEX use a multi-component key; as the name suggests,
34 * the passing of parameters is a bit complex then.
35 * The HASH_KEY_COMPLEX(x) macro should expand to
36 * `x k1, x k2, ... x kn' and you should also define:
37 * HASH_KEY_DECL declaration of function parameters in which key
38 * should be passed to all hash table operations.
39 * That is, `type1 k1, type2 k2, ... typen kn'.
40 * With complex keys, HASH_GIVE_HASHFN and HASH_GIVE_EQ
42 * | HASH_KEY_MEMORY=f use node->f as a raw data key, compared using
44 * HASH_KEY_SIZE the length of the key block
46 * Then specify what operations you request (all names are automatically
47 * prefixed by calling HASH_PREFIX):
49 * <always defined> init() -- initialize the hash table.
50 * HASH_WANT_CLEANUP cleanup() -- deallocate the hash table.
51 * HASH_WANT_FIND node *find(key) -- find first node with the specified
52 * key, return NULL if no such node exists.
53 * HASH_WANT_FIND_NEXT node *find(node *start) -- find next node with the
54 * specified key, return NULL if no such node exists.
55 * HASH_WANT_NEW node *new(key) -- create new node with given key.
56 * Doesn't check whether it already exists.
57 * HASH_WANT_LOOKUP node *lookup(key) -- find node with given key,
58 * if it doesn't exist, create it. Defining
59 * HASH_GIVE_INIT_DATA is strongly recommended.
60 * HASH_WANT_DELETE int delete(key) -- delete and deallocate node
61 * with given key. Returns success.
62 * HASH_WANT_REMOVE remove(node *) -- delete and deallocate given node.
64 * You can also supply several functions:
66 * HASH_GIVE_HASHFN unsigned int hash(key) -- calculate hash value of key.
67 * We have sensible default hash functions for strings
69 * HASH_GIVE_EQ int eq(key1, key2) -- return whether keys are equal.
70 * By default, we use == for atomic types and either
71 * strcmp or strcasecmp for strings.
72 * HASH_GIVE_EXTRA_SIZE int extra_size(key) -- returns how many bytes after the
73 * node should be allocated for dynamic data. Default=0
74 * or length of the string with HASH_KEY_ENDSTRING.
75 * HASH_GIVE_INIT_KEY void init_key(node *,key) -- initialize key in a newly
76 * created node. Defaults: assignment for atomic keys
77 * and static strings, strcpy for end-allocated strings.
78 * HASH_GIVE_INIT_DATA void init_data(node *) -- initialize data fields in a
79 * newly created node. Very useful for lookup operations.
80 * HASH_GIVE_ALLOC void *alloc(unsigned int size) -- allocate space for
81 * a node. Default is xmalloc() or pooled allocation, depending
82 * on HASH_USE_POOL and HASH_AUTO_POOL switches.
83 * void free(void *) -- the converse.
85 * ... and a couple of extra parameters:
87 * HASH_NOCASE String comparisons should be case-insensitive.
88 * HASH_DEFAULT_SIZE=n Initially, use hash table of approx. `n' entries.
89 * HASH_CONSERVE_SPACE Use as little space as possible.
90 * HASH_FN_BITS=n The hash function gives only `n' significant bits.
91 * HASH_ATOMIC_TYPE=t Atomic values are of type `t' instead of int.
92 * HASH_USE_POOL=pool Allocate all nodes from given mempool. Note, however, that
93 * deallocation is not supported by mempools, so delete/remove
94 * will leak pool memory.
95 * HASH_AUTO_POOL=size Create a pool of the given block size automatically.
96 * HASH_ZERO_FILL New entries should be initialized to all zeroes.
97 * HASH_TABLE_ALLOC The hash table itself will be allocated and freed using
98 * the same allocation functions as the nodes instead of
99 * the default xmalloc().
100 * HASH_TABLE_DYNAMIC Support multiple hash tables; the first parameter of all
101 * hash table operations is struct HASH_PREFIX(table) *.
103 * You also get a iterator macro at no extra charge:
105 * HASH_FOR_ALL(hash_prefix, variable)
107 * // node *variable gets declared automatically
108 * do_something_with_node(variable);
109 * // use HASH_BREAK and HASH_CONTINUE instead of break and continue
110 * // you must not alter contents of the hash table here
114 * (For dynamic tables, use HASH_FOR_ALL_DYNAMIC(hash_prefix, hash_table, variable) instead.)
116 * Then include "ucw/hashtable.h" and voila, you have a hash table
117 * suiting all your needs (at least those which you've revealed :) ).
119 * After including this file, all parameter macros are automatically
123 #ifndef _UCW_HASHFUNC_H
124 #include "ucw/hashfunc.h"
127 #include "ucw/prime.h"
131 /* Initial setup of parameters */
133 #if !defined(HASH_NODE) || !defined(HASH_PREFIX)
134 #error Some of the mandatory configuration macros are missing.
137 #if defined(HASH_KEY_ATOMIC) && !defined(HASH_CONSERVE_SPACE)
138 #define HASH_CONSERVE_SPACE
141 #define P(x) HASH_PREFIX(x)
143 /* Declare buckets and the hash table */
145 typedef HASH_NODE P(node);
147 typedef struct P(bucket) {
148 struct P(bucket) *next;
149 #ifndef HASH_CONSERVE_SPACE
157 uns hash_count, hash_max, hash_min, hash_hard_max;
159 #ifdef HASH_AUTO_POOL
160 struct mempool *pool;
164 #ifdef HASH_TABLE_DYNAMIC
166 #define TA struct P(table) *table
168 #define TAU TA UNUSED
169 #define TAUC TA UNUSED,
173 struct P(table) P(table);
183 /* Preset parameters */
185 #if defined(HASH_KEY_ATOMIC)
187 #define HASH_KEY(x) x HASH_KEY_ATOMIC
189 #ifndef HASH_ATOMIC_TYPE
190 # define HASH_ATOMIC_TYPE int
192 #define HASH_KEY_DECL HASH_ATOMIC_TYPE HASH_KEY( )
194 #ifndef HASH_GIVE_HASHFN
195 # define HASH_GIVE_HASHFN
196 static inline int P(hash) (TAUC HASH_ATOMIC_TYPE x)
197 { return ((sizeof(x) <= 4) ? hash_u32(x) : hash_u64(x)); }
201 # define HASH_GIVE_EQ
202 static inline int P(eq) (TAUC HASH_ATOMIC_TYPE x, HASH_ATOMIC_TYPE y)
206 #ifndef HASH_GIVE_INIT_KEY
207 # define HASH_GIVE_INIT_KEY
208 static inline void P(init_key) (TAUC P(node) *n, HASH_ATOMIC_TYPE k)
209 { HASH_KEY(n->) = k; }
212 #elif defined(HASH_KEY_MEMORY)
214 #define HASH_KEY(x) x HASH_KEY_MEMORY
216 #define HASH_KEY_DECL byte HASH_KEY( )[HASH_KEY_SIZE]
218 #ifndef HASH_GIVE_HASHFN
219 # define HASH_GIVE_HASHFN
220 static inline int P(hash) (TAUC byte *x)
221 { return hash_block(x, HASH_KEY_SIZE); }
225 # define HASH_GIVE_EQ
226 static inline int P(eq) (TAUC byte *x, byte *y)
227 { return !memcmp(x, y, HASH_KEY_SIZE); }
230 #ifndef HASH_GIVE_INIT_KEY
231 # define HASH_GIVE_INIT_KEY
232 static inline void P(init_key) (TAUC P(node) *n, byte *k)
233 { memcpy(HASH_KEY(n->), k, HASH_KEY_SIZE); }
236 #elif defined(HASH_KEY_STRING) || defined(HASH_KEY_ENDSTRING)
238 #ifdef HASH_KEY_STRING
239 # define HASH_KEY(x) x HASH_KEY_STRING
240 # ifndef HASH_GIVE_INIT_KEY
241 # define HASH_GIVE_INIT_KEY
242 static inline void P(init_key) (TAUC P(node) *n, char *k)
243 { HASH_KEY(n->) = k; }
246 # define HASH_KEY(x) x HASH_KEY_ENDSTRING
247 # define HASH_GIVE_EXTRA_SIZE
248 static inline int P(extra_size) (TAUC char *k)
249 { return strlen(k); }
250 # ifndef HASH_GIVE_INIT_KEY
251 # define HASH_GIVE_INIT_KEY
252 static inline void P(init_key) (TAUC P(node) *n, char *k)
253 { strcpy(HASH_KEY(n->), k); }
256 #define HASH_KEY_DECL char *HASH_KEY( )
258 #ifndef HASH_GIVE_HASHFN
259 #define HASH_GIVE_HASHFN
260 static inline uns P(hash) (TAUC char *k)
263 return hash_string_nocase(k);
265 return hash_string(k);
271 # define HASH_GIVE_EQ
272 static inline int P(eq) (TAUC char *x, char *y)
275 return !strcasecmp(x,y);
282 #elif defined(HASH_KEY_COMPLEX)
284 #define HASH_KEY(x) HASH_KEY_COMPLEX(x)
287 #error You forgot to set the hash key type.
290 /* Defaults for missing parameters */
292 #ifndef HASH_GIVE_HASHFN
293 #error Unable to determine which hash function to use.
297 #error Unable to determine how to compare two keys.
300 #ifdef HASH_GIVE_EXTRA_SIZE
301 /* This trickery is needed to avoid `unused parameter' warnings */
302 #define HASH_EXTRA_SIZE(x) P(extra_size)(TTC x)
305 * Beware, C macros are expanded iteratively, not recursively,
306 * hence we get only a _single_ argument, although the expansion
307 * of HASH_KEY contains commas.
309 #define HASH_EXTRA_SIZE(x) 0
312 #ifndef HASH_GIVE_INIT_KEY
313 #error Unable to determine how to initialize keys.
316 #ifndef HASH_GIVE_INIT_DATA
317 static inline void P(init_data) (TAUC P(node) *n UNUSED)
322 #ifdef HASH_GIVE_ALLOC
323 /* If the caller has requested to use his own allocation functions, do so */
324 static inline void P(init_alloc) (TAU) { }
325 static inline void P(cleanup_alloc) (TAU) { }
327 #elif defined(HASH_USE_POOL)
328 /* If the caller has requested to use his mempool, do so */
329 #include "ucw/mempool.h"
330 static inline void * P(alloc) (TAUC unsigned int size) { return mp_alloc_fast(HASH_USE_POOL, size); }
331 static inline void P(free) (TAUC void *x UNUSED) { }
332 static inline void P(init_alloc) (TAU) { }
333 static inline void P(cleanup_alloc) (TAU) { }
335 #elif defined(HASH_AUTO_POOL)
336 /* Use our own pools */
337 #include "ucw/mempool.h"
338 static inline void * P(alloc) (TAUC unsigned int size) { return mp_alloc_fast(T.pool, size); }
339 static inline void P(free) (TAUC void *x UNUSED) { }
340 static inline void P(init_alloc) (TAU) { T.pool = mp_new(HASH_AUTO_POOL); }
341 static inline void P(cleanup_alloc) (TAU) { mp_delete(T.pool); }
342 #define HASH_USE_POOL
345 /* The default allocation method */
346 static inline void * P(alloc) (TAUC unsigned int size) { return xmalloc(size); }
347 static inline void P(free) (TAUC void *x) { xfree(x); }
348 static inline void P(init_alloc) (TAU) { }
349 static inline void P(cleanup_alloc) (TAU) { }
353 #ifdef HASH_TABLE_ALLOC
354 static inline void * P(table_alloc) (TAUC unsigned int size) { return P(alloc)(TTC size); }
355 static inline void P(table_free) (TAUC void *x) { P(free)(TTC x); }
357 static inline void * P(table_alloc) (TAUC unsigned int size) { return xmalloc(size); }
358 static inline void P(table_free) (TAUC void *x) { xfree(x); }
361 #ifndef HASH_DEFAULT_SIZE
362 #define HASH_DEFAULT_SIZE 32
366 #define HASH_FN_BITS 32
369 #ifdef HASH_ZERO_FILL
370 static inline void * P(new_bucket)(TAUC uns size)
372 byte *buck = P(alloc)(TTC size);
377 static inline void * P(new_bucket)(TAUC uns size) { return P(alloc)(TTC size); }
380 /* Now the operations */
382 static void P(alloc_table) (TAU)
384 T.hash_size = next_table_prime(T.hash_size);
385 T.ht = P(table_alloc)(TTC sizeof(void *) * T.hash_size);
386 bzero(T.ht, sizeof(void *) * T.hash_size);
387 if (2*T.hash_size < T.hash_hard_max)
388 T.hash_max = 2*T.hash_size;
391 if (T.hash_size/2 > HASH_DEFAULT_SIZE)
392 T.hash_min = T.hash_size/4;
397 static void P(init) (TA)
400 T.hash_size = HASH_DEFAULT_SIZE;
401 #if HASH_FN_BITS < 28
402 T.hash_hard_max = 1 << HASH_FN_BITS;
404 T.hash_hard_max = 1 << 28;
410 #ifdef HASH_WANT_CLEANUP
411 static void P(cleanup) (TA)
413 #ifndef HASH_USE_POOL
417 for (i=0; i<T.hash_size; i++)
418 for (b=T.ht[i]; b; b=bb)
424 P(cleanup_alloc)(TT);
425 P(table_free)(TTC T.ht);
429 static inline uns P(bucket_hash) (TAUC P(bucket) *b)
431 #ifdef HASH_CONSERVE_SPACE
432 return P(hash)(TTC HASH_KEY(b->n.));
438 static void P(rehash) (TAC uns size)
441 P(bucket) **oldt = T.ht, **newt;
442 uns oldsize = T.hash_size;
445 DBG("Rehashing %d->%d at count %d", oldsize, size, T.hash_count);
449 for (i=0; i<oldsize; i++)
455 h = P(bucket_hash)(TTC b) % T.hash_size;
461 P(table_free)(TTC oldt);
464 #ifdef HASH_WANT_FIND
465 static P(node) * P(find) (TAC HASH_KEY_DECL)
467 uns h0 = P(hash) (TTC HASH_KEY( ));
468 uns h = h0 % T.hash_size;
471 for (b=T.ht[h]; b; b=b->next)
474 #ifndef HASH_CONSERVE_SPACE
477 P(eq)(TTC HASH_KEY( ), HASH_KEY(b->n.)))
484 #ifdef HASH_WANT_FIND_NEXT
485 static P(node) * P(find_next) (TAC P(node) *start)
487 #ifndef HASH_CONSERVE_SPACE
488 uns h0 = P(hash) (TTC HASH_KEY(start->));
490 P(bucket) *b = SKIP_BACK(P(bucket), n, start);
492 for (b=b->next; b; b=b->next)
495 #ifndef HASH_CONSERVE_SPACE
498 P(eq)(TTC HASH_KEY(start->), HASH_KEY(b->n.)))
506 static P(node) * P(new) (TAC HASH_KEY_DECL)
511 h0 = P(hash) (TTC HASH_KEY( ));
512 h = h0 % T.hash_size;
513 b = P(new_bucket) (TTC sizeof(struct P(bucket)) + HASH_EXTRA_SIZE(HASH_KEY( )));
516 #ifndef HASH_CONSERVE_SPACE
519 P(init_key)(TTC &b->n, HASH_KEY( ));
520 P(init_data)(TTC &b->n);
521 if (T.hash_count++ >= T.hash_max)
522 P(rehash)(TTC 2*T.hash_size);
527 #ifdef HASH_WANT_LOOKUP
528 static P(node) * P(lookup) (TAC HASH_KEY_DECL)
530 uns h0 = P(hash) (TTC HASH_KEY( ));
531 uns h = h0 % T.hash_size;
534 for (b=T.ht[h]; b; b=b->next)
537 #ifndef HASH_CONSERVE_SPACE
540 P(eq)(TTC HASH_KEY( ), HASH_KEY(b->n.)))
544 b = P(new_bucket) (TTC sizeof(struct P(bucket)) + HASH_EXTRA_SIZE(HASH_KEY( )));
547 #ifndef HASH_CONSERVE_SPACE
550 P(init_key)(TTC &b->n, HASH_KEY( ));
551 P(init_data)(TTC &b->n);
552 if (T.hash_count++ >= T.hash_max)
553 P(rehash)(TTC 2*T.hash_size);
558 #ifdef HASH_WANT_DELETE
559 static int P(delete) (TAC HASH_KEY_DECL)
561 uns h0 = P(hash) (TTC HASH_KEY( ));
562 uns h = h0 % T.hash_size;
565 for (bb=&T.ht[h]; b=*bb; bb=&b->next)
568 #ifndef HASH_CONSERVE_SPACE
571 P(eq)(TTC HASH_KEY( ), HASH_KEY(b->n.)))
575 if (--T.hash_count < T.hash_min)
576 P(rehash)(TTC T.hash_size/2);
584 #ifdef HASH_WANT_REMOVE
585 static void P(remove) (TAC P(node) *n)
587 P(bucket) *x = SKIP_BACK(struct P(bucket), n, n);
588 uns h0 = P(bucket_hash)(TTC x);
589 uns h = h0 % T.hash_size;
592 for (bb=&T.ht[h]; (b=*bb) && b != x; bb=&b->next)
597 if (--T.hash_count < T.hash_min)
598 P(rehash)(TTC T.hash_size/2);
602 /* And the iterator */
606 #define HASH_FOR_ALL_DYNAMIC(h_px, h_table, h_var) \
609 struct GLUE_(h_px,bucket) *h_buck; \
610 for (h_slot=0; h_slot < (h_table)->hash_size; h_slot++) \
611 for (h_buck = (h_table)->ht[h_slot]; h_buck; h_buck = h_buck->next) \
613 GLUE_(h_px,node) *h_var = &h_buck->n;
614 #define HASH_FOR_ALL(h_px, h_var) HASH_FOR_ALL_DYNAMIC(h_px, &GLUE_(h_px,table), h_var)
615 #define HASH_END_FOR } } while(0)
617 #define HASH_CONTINUE continue
621 /* Finally, undefine all the parameters */
632 #undef HASH_ATOMIC_TYPE
633 #undef HASH_CONSERVE_SPACE
634 #undef HASH_DEFAULT_SIZE
635 #undef HASH_EXTRA_SIZE
637 #undef HASH_GIVE_ALLOC
639 #undef HASH_GIVE_EXTRA_SIZE
640 #undef HASH_GIVE_HASHFN
641 #undef HASH_GIVE_INIT_DATA
642 #undef HASH_GIVE_INIT_KEY
644 #undef HASH_KEY_ATOMIC
645 #undef HASH_KEY_COMPLEX
647 #undef HASH_KEY_ENDSTRING
648 #undef HASH_KEY_STRING
649 #undef HASH_KEY_MEMORY
655 #undef HASH_AUTO_POOL
656 #undef HASH_WANT_CLEANUP
657 #undef HASH_WANT_DELETE
658 #undef HASH_WANT_FIND
659 #undef HASH_WANT_FIND_NEXT
660 #undef HASH_WANT_LOOKUP
662 #undef HASH_WANT_REMOVE
663 #undef HASH_TABLE_ALLOC
664 #undef HASH_TABLE_DYNAMIC
665 #undef HASH_ZERO_FILL