X-Git-Url: https://git.liburcu.org/?p=urcu.git;a=blobdiff_plain;f=urcu%2Frculfhash.h;h=7a411ad688ee92cbd753a7f04f798f355179beca;hp=2d8a3104d7c18f5e94a5677c5fcca9870363b12d;hb=28d5c1b5f2bdbb630c4aafa35c9b6e0d58542c73;hpb=3a9c66db35077a0437810157ba362a68262048de diff --git a/urcu/rculfhash.h b/urcu/rculfhash.h index 2d8a310..7a411ad 100644 --- 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, @@ -203,7 +210,9 @@ void cds_lfht_count_nodes(struct cds_lfht *ht, * * Call with rcu_read_lock held. * 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); @@ -226,7 +235,9 @@ void cds_lfht_lookup(struct cds_lfht *ht, unsigned long hash, * node returned by a previous cds_lfht_next. * Call with rcu_read_lock held. * 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); @@ -239,7 +250,9 @@ void cds_lfht_next_duplicate(struct cds_lfht *ht, * Output in "*iter". *iter->node set to NULL if table is empty. * Call with rcu_read_lock held. * 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); /* @@ -252,7 +265,9 @@ void cds_lfht_first(struct cds_lfht *ht, struct cds_lfht_iter *iter); * pointing to the last table node. * Call with rcu_read_lock held. * 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); /* @@ -264,7 +279,10 @@ void cds_lfht_next(struct cds_lfht *ht, struct cds_lfht_iter *iter); * This function supports adding redundant keys into the table. * Call with rcu_read_lock held. * Threads calling this API need to be registered RCU read-side threads. + * 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); @@ -288,7 +306,14 @@ void cds_lfht_add(struct cds_lfht *ht, unsigned long hash, * to add keys into the table, no duplicated keys should ever be * observable in the table. The same guarantee apply for combination of * add_unique and add_replace (see below). + * + * Upon success, this function issues a full memory barrier before and + * after its atomic commit. Upon failure, this function acts like a + * simple lookup operation: it acts as a rcu_dereference() to read the + * 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, @@ -321,7 +346,11 @@ struct cds_lfht_node *cds_lfht_add_unique(struct cds_lfht *ht, * schemes will never generate duplicated keys. It also allows us to * guarantee that a combination of add_replace and add_unique updates * will never generate duplicated keys. + * + * 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, @@ -352,7 +381,12 @@ struct cds_lfht_node *cds_lfht_add_replace(struct cds_lfht *ht, * * The semantic of replacement vs lookups is the same as * cds_lfht_add_replace(). + * + * Upon success, this function issues a full memory barrier before and + * 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, @@ -377,7 +411,11 @@ int cds_lfht_replace(struct cds_lfht *ht, * After successful removal, a grace period must be waited for before * freeing the memory reserved for old node (which can be accessed with * cds_lfht_iter_get_node). + * Upon success, this function issues a full memory barrier before and + * 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); /* @@ -391,7 +429,9 @@ int cds_lfht_del(struct cds_lfht *ht, struct cds_lfht_node *node); * function. * Call with rcu_read_lock held. * 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); /* @@ -400,13 +440,18 @@ int cds_lfht_is_node_deleted(struct cds_lfht_node *node); * @new_size: update to this hash table size. * * 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); /* * Note: it is safe to perform element removal (del), replacement, or * any hash table update operation during any of the following hash * table traversals. + * These functions act as rcu_dereference() to read the node pointers. */ #define cds_lfht_for_each(ht, iter, node) \ for (cds_lfht_first(ht, iter), \ @@ -425,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 }