* @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.
*
* 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 call_rcu thread context
+ * neither.
+ * In userspace RCU 0.7.x, for QSBR RCU flavor, cds_lfht_destroy() has a
+ * side-effect: it puts the caller thread in "online" state. This will
+ * be fixed in userspace RCU 0.8.x.
*/
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.
+ * This function acts as a rcu_dereference() to read the node pointer.
*/
void cds_lfht_lookup(struct cds_lfht *ht, unsigned long hash,
cds_lfht_match_fct match, const void *key,
* 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.
*/
void cds_lfht_next_duplicate(struct cds_lfht *ht,
cds_lfht_match_fct match, const void *key,
* 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.
*/
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.
*/
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.
*/
void cds_lfht_add(struct cds_lfht *ht, unsigned long hash,
struct cds_lfht_node *node);
* 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.
*/
struct cds_lfht_node *cds_lfht_add_unique(struct cds_lfht *ht,
unsigned long hash,
* 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.
*/
struct cds_lfht_node *cds_lfht_add_replace(struct cds_lfht *ht,
unsigned long hash,
*
* 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.
*/
int cds_lfht_replace(struct cds_lfht *ht,
struct cds_lfht_iter *old_iter,
* 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.
*/
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.
*/
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.
+ * In userspace RCU 0.7.x, for QSBR RCU flavor, cds_lfht_resize() has a
+ * side-effect: it puts the caller thread in "online" state. This will
+ * be fixed in userspace RCU 0.8.x.
*/
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), \
#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
}
projects / userspace-rcu.git / blobdiff