Hashtable routines.
[ccan] / ccan / hashtable / hashtable.h
1 #ifndef CCAN_HASHTABLE_H
2 #define CCAN_HASHTABLE_H
3 #include "config.h"
4 #include <stdbool.h>
5
6 struct hashtable;
7
8 /**
9  * hashtable_new - allocate a hash tree.
10  * @rehash: hash function to use for rehashing.
11  * @priv: private argument to @rehash function.
12  */
13 struct hashtable *hashtable_new(unsigned long (*rehash)(const void *elem,
14                                                         void *priv),
15                                 void *priv);
16
17 /**
18  * hashtable_free - dellocate a hash tree.
19  *
20  * This doesn't do anything to any pointers left in it.
21  */
22 void hashtable_free(struct hashtable *);
23
24 /**
25  * hashtable_find - look for an object in a hash tree.
26  * @ht: the hashtable
27  * @hash: the hash value of the object you are seeking
28  * @cmp: a comparison function: returns true if the object is found
29  * @cmpdata: the data to hand as second arg to @cmp
30  *
31  * Note that you can do all the work inside the cmp function if you want to:
32  * hashtable_find will return @htelem if @cmp returns true.
33  */
34 void *hashtable_find(struct hashtable *ht,
35                      unsigned long hash,
36                      bool (*cmp)(const void *htelem, void *cmpdata),
37                      void *cmpdata);
38
39 /**
40  * hashtable_add - add an (aligned) pointer into a hash tree.
41  * @ht: the hashtable
42  * @hash: the hash value of the object
43  * @p: the non-NULL pointer, usually from malloc or equiv.
44  *
45  * Note that this implementation (ab)uses the lower bits of the pointer, so
46  * it will abort if the pointer is not aligned to 8 bytes.
47  *
48  * Also note that this can only fail due to allocation failure.  Otherwise, it
49  * returns true.
50  */
51 bool hashtable_add(struct hashtable *ht, unsigned long hash, const void *p);
52
53 /**
54  * hashtable_del - remove a pointer from a hash tree
55  * @ht: the hashtable
56  * @hash: the hash value of the object
57  * @p: the pointer
58  *
59  * Returns true if the pointer was found (and deleted).
60  */
61 bool hashtable_del(struct hashtable *ht, unsigned long hash, const void *p);
62
63 /**
64  * hashtable_traverse - call a function on every pointer in hash tree
65  * @ht: the hashtable
66  * @cb: the callback: returns true to abort traversal.
67  * @cbarg: the argument to the callback
68  *
69  * Note that your traversal callback may delete any entry (it won't crash),
70  * but it may make the traverse unreliable.
71  */
72 void hashtable_traverse(struct hashtable *ht, bool (*cb)(void *p, void *cbarg),
73                         void *cbarg);
74 #endif /* CCAN_HASHTABLE_H */