2 * Copyright (C) 1998 Kunihiro Ishiguro
4 * This file is part of GNU Zebra.
6 * GNU Zebra is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published
8 * by the Free Software Foundation; either version 2, or (at your
9 * option) any later version.
11 * GNU Zebra is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * General Public License for more details.
16 * You should have received a copy of the GNU General Public License along
17 * with this program; see the file COPYING; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
25 #include "frratomic.h"
31 /* Default hash table size. */
32 #define HASH_INITIAL_SIZE 256
33 /* Expansion threshold */
34 #define HASH_THRESHOLD(used, size) ((used) > (size))
36 #define HASHWALK_CONTINUE 0
37 #define HASHWALK_ABORT -1
39 #if CONFDATE > 20200225
40 CPP_NOTICE("hash.h: time to remove hash_backet #define")
42 #define hash_backet hash_bucket
46 * if this bucket is the head of the linked listed, len denotes the
47 * number of elements in the list
52 struct hash_bucket
*next
;
62 /* number of empty hash buckets */
63 atomic_uint_fast32_t empty
;
64 /* sum of squares of bucket length */
65 atomic_uint_fast32_t ssq
;
70 struct hash_bucket
**index
;
72 /* Hash table size. Must be power of 2 */
75 /* If max_size is 0 there is no limit */
76 unsigned int max_size
;
78 /* Key make function. */
79 unsigned int (*hash_key
)(const void *);
81 /* Data compare function. */
82 bool (*hash_cmp
)(const void *, const void *);
87 struct hashstats stats
;
93 #define hashcount(X) ((X)->count)
96 * Create a hash table.
98 * The created hash table uses chaining and a user-provided comparator function
99 * to resolve collisions. For best performance use a perfect hash function.
100 * Worst case lookup time is O(N) when using a constant hash function. Best
101 * case lookup time is O(1) when using a perfect hash function.
103 * The initial size of the created hash table is HASH_INITIAL_SIZE.
106 * hash function to use; should return a unique unsigned integer when called
107 * with a data item. Collisions are acceptable.
110 * comparison function used for resolving collisions; when called with two
111 * data items, should return nonzero if the two items are equal and 0
115 * optional name for the hashtable; this is used when displaying global
116 * hashtable statistics. If this parameter is NULL the hash's name will be
117 * set to NULL and the default name will be displayed when showing
123 extern struct hash
*hash_create(unsigned int (*hash_key
)(const void *),
124 bool (*hash_cmp
)(const void *, const void *),
128 * Create a hash table.
130 * The created hash table uses chaining and a user-provided comparator function
131 * to resolve collisions. For best performance use a perfect hash function.
132 * Worst case lookup time is O(N) when using a constant hash function. Best
133 * case lookup time is O(1) when using a perfect hash function.
136 * initial number of hash buckets to allocate; must be a power of 2 or the
137 * program will assert
140 * hash function to use; should return a unique unsigned integer when called
141 * with a data item. Collisions are acceptable.
144 * comparison function used for resolving collisions; when called with two
145 * data items, should return nonzero if the two items are equal and 0
149 * optional name for the hashtable; this is used when displaying global
150 * hashtable statistics. If this parameter is NULL the hash's name will be
151 * set to NULL and the default name will be displayed when showing
158 hash_create_size(unsigned int size
, unsigned int (*hash_key
)(const void *),
159 bool (*hash_cmp
)(const void *, const void *),
163 * Retrieve or insert data from / into a hash table.
165 * This function is somewhat counterintuitive in its usage. In order to look up
166 * an element from its key, you must provide the data item itself, with the
167 * portions used in the hash function set to the same values as the data item
168 * to retrieve. To insert a data element, either provide the key as just
169 * described and provide alloc_func as descrbied below to allocate the full
170 * data element, or provide the full data element and pass 'hash_alloc_intern'
174 * hash table to operate on
177 * data to insert or retrieve - A hash bucket will not be created if
178 * the alloc_func returns a NULL pointer and nothing will be added to
179 * the hash. As such bucket->data will always be non-NULL.
182 * function to call if the item is not found in the hash table. This
183 * function is called with the value of 'data' and should create the data
184 * item to insert and return a pointer to it. If the data has already been
185 * completely created and provided in the 'data' parameter, passing
186 * 'hash_alloc_intern' to this parameter will cause 'data' to be inserted.
187 * If this parameter is NULL, then this call to hash_get is equivalent to
191 * the data item found or inserted, or NULL if alloc_func is NULL and the
194 extern void *hash_get(struct hash
*hash
, void *data
,
195 void *(*alloc_func
)(void *));
198 * Dummy element allocation function.
200 * See hash_get for details.
203 * data to insert into the hash table
208 extern void *hash_alloc_intern(void *data
);
211 * Retrieve an item from a hash table.
213 * This function is equivalent to calling hash_get with alloc_func set to NULL.
216 * hash table to operate on
219 * data element with values used for key computation set
222 * the data element if found, or NULL if not found
224 extern void *hash_lookup(struct hash
*hash
, void *data
);
227 * Remove an element from a hash table.
230 * hash table to operate on
233 * data element to remove with values used for key computation set
236 * the removed element if found, or NULL if not found
238 extern void *hash_release(struct hash
*hash
, void *data
);
241 * Iterate over the elements in a hash table.
243 * It is safe to delete items passed to the iteration function from the hash
244 * table during iteration. Please note that adding entries to the hash
245 * during the walk will cause undefined behavior in that some new entries
246 * will be walked and some will not. So do not do this.
248 * The bucket passed to func will have a non-NULL data pointer.
251 * hash table to operate on
254 * function to call with each data item
257 * arbitrary argument passed as the second parameter in each call to 'func'
259 extern void hash_iterate(struct hash
*hash
,
260 void (*func
)(struct hash_bucket
*, void *), void *arg
);
263 * Iterate over the elements in a hash table, stopping on condition.
265 * It is safe to delete items passed to the iteration function from the hash
266 * table during iteration. Please note that adding entries to the hash
267 * during the walk will cause undefined behavior in that some new entries
268 * will be walked and some will not. So do not do this.
270 * The bucket passed to func will have a non-NULL data pointer.
273 * hash table to operate on
276 * function to call with each data item. If this function returns
277 * HASHWALK_ABORT then the iteration stops.
280 * arbitrary argument passed as the second parameter in each call to 'func'
282 extern void hash_walk(struct hash
*hash
,
283 int (*func
)(struct hash_bucket
*, void *), void *arg
);
286 * Remove all elements from a hash table.
289 * hash table to operate on
292 * function to call with each removed item; intended to free the data
294 extern void hash_clean(struct hash
*hash
, void (*free_func
)(void *));
297 * Delete a hash table.
299 * This function assumes the table is empty. Call hash_clean to delete the
300 * hashtable contents if necessary.
303 * hash table to delete
305 extern void hash_free(struct hash
*hash
);
308 * Converts a hash table to an unsorted linked list.
309 * Does not modify the hash table in any way.
312 * hash table to convert
314 extern struct list
*hash_to_list(struct hash
*hash
);
317 * Hash a string using the modified Bernstein hash.
319 * This is not a perfect hash function.
325 * modified Bernstein hash of the string
327 extern unsigned int string_hash_make(const char *);
330 * Install CLI commands for viewing global hash table statistics.
332 extern void hash_cmd_init(void);
338 #endif /* _ZEBRA_HASH_H */