lib/ccan/htable/htable.h

   1 #ifndef CCAN_HTABLE_H
   2 #define CCAN_HTABLE_H
   3 #include "config.h"
   4 #include <stdbool.h>
   5 #include <stdlib.h>
   6
   7 struct htable;
   8
   9 /**
  10  * htable_new - allocate a hash tree.
  11  * @rehash: hash function to use for rehashing.
  12  * @priv: private argument to @rehash function.
  13  */
  14 struct htable *htable_new(size_t (*hash)(const void *elem, void *priv),
  15                           void *priv);
  16
  17 /**
  18  * htable_free - dellocate a hash tree.
  19  *
  20  * This doesn't do anything to any pointers left in it.
  21  */
  22 void htable_free(const struct htable *);
  23
  24 /**
  25  * htable_rehash - use a hashtree's rehash function
  26  * @elem: the argument to rehash()
  27  *
  28  */
  29 size_t htable_rehash(const void *elem);
  30
  31 /**
  32  * htable_add - add a pointer into a hash tree.
  33  * @ht: the htable
  34  * @hash: the hash value of the object
  35  * @p: the non-NULL pointer
  36  *
  37  * Also note that this can only fail due to allocation failure.  Otherwise, it
  38  * returns true.
  39  */
  40 bool htable_add(struct htable *ht, size_t hash, const void *p);
  41
  42 /**
  43  * htable_del - remove a pointer from a hash tree
  44  * @ht: the htable
  45  * @hash: the hash value of the object
  46  * @p: the pointer
  47  *
  48  * Returns true if the pointer was found (and deleted).
  49  */
  50 bool htable_del(struct htable *ht, size_t hash, const void *p);
  51
  52 /**
  53  * struct htable_iter - iterator or htable_first or htable_firstval etc.
  54  *
  55  * This refers to a location inside the hashtable.
  56  */
  57 struct htable_iter {
  58         size_t off;
  59 };
  60
  61 /**
  62  * htable_firstval - find a candidate for a given hash value
  63  * @htable: the hashtable
  64  * @i: the struct htable_iter to initialize
  65  * @hash: the hash value
  66  *
  67  * You'll need to check the value is what you want; returns NULL if none.
  68  * See Also:
  69  *      htable_delval()
  70  */
  71 void *htable_firstval(const struct htable *htable,
  72                       struct htable_iter *i, size_t hash);
  73
  74 /**
  75  * htable_nextval - find another candidate for a given hash value
  76  * @htable: the hashtable
  77  * @i: the struct htable_iter to initialize
  78  * @hash: the hash value
  79  *
  80  * You'll need to check the value is what you want; returns NULL if no more.
  81  */
  82 void *htable_nextval(const struct htable *htable,
  83                      struct htable_iter *i, size_t hash);
  84
  85 /**
  86  * htable_get - find an entry in the hash table
  87  * @ht: the hashtable
  88  * @h: the hash value of the entry
  89  * @cmp: the comparison function
  90  * @ptr: the pointer to hand to the comparison function.
  91  *
  92  * Convenient inline wrapper for htable_firstval/htable_nextval loop.
  93  */
  94 static inline void *htable_get(const struct htable *ht,
  95                                size_t h,
  96                                bool (*cmp)(const void *candidate, void *ptr),
  97                                const void *ptr)
  98 {
  99         struct htable_iter i;
 100         void *c;
 101
 102         for (c = htable_firstval(ht,&i,h); c; c = htable_nextval(ht,&i,h)) {
 103                 if (cmp(c, (void *)ptr))
 104                         return c;
 105         }
 106         return NULL;
 107 }
 108
 109 /**
 110  * htable_first - find an entry in the hash table
 111  * @ht: the hashtable
 112  * @i: the struct htable_iter to initialize
 113  *
 114  * Get an entry in the hashtable; NULL if empty.
 115  */
 116 void *htable_first(const struct htable *htable, struct htable_iter *i);
 117
 118 /**
 119  * htable_next - find another entry in the hash table
 120  * @ht: the hashtable
 121  * @i: the struct htable_iter to use
 122  *
 123  * Get another entry in the hashtable; NULL if all done.
 124  * This is usually used after htable_first or prior non-NULL htable_next.
 125  */
 126 void *htable_next(const struct htable *htable, struct htable_iter *i);
 127
 128 /**
 129  * htable_delval - remove an iterated pointer from a hash tree
 130  * @ht: the htable
 131  * @i: the htable_iter
 132  *
 133  * Usually used to delete a hash entry after it has been found with
 134  * htable_firstval etc.
 135  */
 136 void htable_delval(struct htable *ht, struct htable_iter *i);
 137
 138 #endif /* CCAN_HTABLE_H */