rculfhash: document max_nr_buckets = 0

[urcu.git] / urcu / rculfhash.h

diff --git a/urcu/rculfhash.h b/urcu/rculfhash.h
index 2938e5ec6235883acc9efb9b029e135035f7a10e..7a411ad688ee92cbd753a7f04f798f355179beca 100644 (file)
--- a/urcu/rculfhash.h
+++ b/urcu/rculfhash.h
@@ -118,6 +118,7 @@ extern const struct cds_lfht_mm_type cds_lfht_mm_mmap;
 /*
  * _cds_lfht_new - API used by cds_lfht_new wrapper. Do not use directly.
  */
+extern
 struct cds_lfht *_cds_lfht_new(unsigned long init_size,
                        unsigned long min_nr_alloc_buckets,
                        unsigned long max_nr_buckets,
@@ -132,7 +133,8 @@ struct cds_lfht *_cds_lfht_new(unsigned long init_size,
  * @min_nr_alloc_buckets: the minimum number of allocated buckets.
  *                        (must be power of two)
  * @max_nr_buckets: the maximum number of hash table buckets allowed.
- *                  (must be power of two)
+ *                  (must be power of two, 0 is accepted, means
+ *                  "infinite")
  * @flags: hash table creation flags (can be combined with bitwise or: '|').
  *           0: no flags.
  *           CDS_LFHT_AUTO_RESIZE: automatically resize hash table.
@@ -175,7 +177,11 @@ struct cds_lfht *cds_lfht_new(unsigned long init_size,
  *
  * Return 0 on success, negative error value on error.
  * Threads calling this API need to be registered RCU read-side threads.
+ * cds_lfht_destroy should *not* be called from a RCU read-side critical
+ * section. It should *not* be called from a call_rcu thread context
+ * neither.
  */
+extern
 int cds_lfht_destroy(struct cds_lfht *ht, pthread_attr_t **attr);
 
 /*
@@ -188,6 +194,7 @@ int cds_lfht_destroy(struct cds_lfht *ht, pthread_attr_t **attr);
  * Call with rcu_read_lock held.
  * Threads calling this API need to be registered RCU read-side threads.
  */
+extern
 void cds_lfht_count_nodes(struct cds_lfht *ht,
                long *split_count_before,
                unsigned long *count,
@@ -205,6 +212,7 @@ void cds_lfht_count_nodes(struct cds_lfht *ht,
  * Threads calling this API need to be registered RCU read-side threads.
  * This function acts as a rcu_dereference() to read the node pointer.
  */
+extern
 void cds_lfht_lookup(struct cds_lfht *ht, unsigned long hash,
                cds_lfht_match_fct match, const void *key,
                struct cds_lfht_iter *iter);
@@ -229,6 +237,7 @@ void cds_lfht_lookup(struct cds_lfht *ht, unsigned long hash,
  * Threads calling this API need to be registered RCU read-side threads.
  * This function acts as a rcu_dereference() to read the node pointer.
  */
+extern
 void cds_lfht_next_duplicate(struct cds_lfht *ht,
                cds_lfht_match_fct match, const void *key,
                struct cds_lfht_iter *iter);
@@ -243,6 +252,7 @@ void cds_lfht_next_duplicate(struct cds_lfht *ht,
  * Threads calling this API need to be registered RCU read-side threads.
  * This function acts as a rcu_dereference() to read the node pointer.
  */
+extern
 void cds_lfht_first(struct cds_lfht *ht, struct cds_lfht_iter *iter);
 
 /*
@@ -257,6 +267,7 @@ void cds_lfht_first(struct cds_lfht *ht, struct cds_lfht_iter *iter);
  * Threads calling this API need to be registered RCU read-side threads.
  * This function acts as a rcu_dereference() to read the node pointer.
  */
+extern
 void cds_lfht_next(struct cds_lfht *ht, struct cds_lfht_iter *iter);
 
 /*
@@ -271,6 +282,7 @@ void cds_lfht_next(struct cds_lfht *ht, struct cds_lfht_iter *iter);
  * This function issues a full memory barrier before and after its
  * atomic commit.
  */
+extern
 void cds_lfht_add(struct cds_lfht *ht, unsigned long hash,
                struct cds_lfht_node *node);
 
@@ -301,6 +313,7 @@ void cds_lfht_add(struct cds_lfht *ht, unsigned long hash,
  * node pointer. The failure case does not guarantee any other memory
  * barrier.
  */
+extern
 struct cds_lfht_node *cds_lfht_add_unique(struct cds_lfht *ht,
                unsigned long hash,
                cds_lfht_match_fct match,
@@ -337,6 +350,7 @@ struct cds_lfht_node *cds_lfht_add_unique(struct cds_lfht *ht,
  * This function issues a full memory barrier before and after its
  * atomic commit.
  */
+extern
 struct cds_lfht_node *cds_lfht_add_replace(struct cds_lfht *ht,
                unsigned long hash,
                cds_lfht_match_fct match,
@@ -372,6 +386,7 @@ struct cds_lfht_node *cds_lfht_add_replace(struct cds_lfht *ht,
  * after its atomic commit. Upon failure, this function does not issue
  * any memory barrier.
  */
+extern
 int cds_lfht_replace(struct cds_lfht *ht,
                struct cds_lfht_iter *old_iter,
                unsigned long hash,
@@ -400,6 +415,7 @@ int cds_lfht_replace(struct cds_lfht *ht,
  * after its atomic commit. Upon failure, this function does not issue
  * any memory barrier.
  */
+extern
 int cds_lfht_del(struct cds_lfht *ht, struct cds_lfht_node *node);
 
 /*
@@ -415,6 +431,7 @@ int cds_lfht_del(struct cds_lfht *ht, struct cds_lfht_node *node);
  * Threads calling this API need to be registered RCU read-side threads.
  * This function does not issue any memory barrier.
  */
+extern
 int cds_lfht_is_node_deleted(struct cds_lfht_node *node);
 
 /*
@@ -424,7 +441,10 @@ int cds_lfht_is_node_deleted(struct cds_lfht_node *node);
  *
  * Threads calling this API need to be registered RCU read-side threads.
  * This function does not (necessarily) issue memory barriers.
+ * cds_lfht_resize should *not* be called from a RCU read-side critical
+ * section.
  */
+extern
 void cds_lfht_resize(struct cds_lfht *ht, unsigned long new_size);
 
 /*
@@ -450,21 +470,21 @@ void cds_lfht_resize(struct cds_lfht *ht, unsigned long new_size);
 #define cds_lfht_for_each_entry(ht, iter, pos, member)                 \
        for (cds_lfht_first(ht, iter),                                  \
                        pos = caa_container_of(cds_lfht_iter_get_node(iter), \
-                                       typeof(*(pos)), member);        \
+                                       __typeof__(*(pos)), member);    \
                &(pos)->member != NULL;                                 \
                cds_lfht_next(ht, iter),                                \
                        pos = caa_container_of(cds_lfht_iter_get_node(iter), \
-                                       typeof(*(pos)), member))
+                                       __typeof__(*(pos)), member))
 
 #define cds_lfht_for_each_entry_duplicate(ht, hash, match, key,                \
                                iter, pos, member)                      \
        for (cds_lfht_lookup(ht, hash, match, key, iter),               \
                        pos = caa_container_of(cds_lfht_iter_get_node(iter), \
-                                       typeof(*(pos)), member);        \
+                                       __typeof__(*(pos)), member);    \
                &(pos)->member != NULL;                                 \
                cds_lfht_next_duplicate(ht, match, key, iter),          \
                        pos = caa_container_of(cds_lfht_iter_get_node(iter), \
-                                       typeof(*(pos)), member))
+                                       __typeof__(*(pos)), member))
 
 #ifdef __cplusplus
 }