From 7f52427be704778d53f85e17fb71629b50ada827 Mon Sep 17 00:00:00 2001 From: Mathieu Desnoyers Date: Tue, 1 Nov 2011 15:45:01 -0400 Subject: [PATCH] Add structure descriptions, remove redundant clear_flag() Reported-by: Paul E. McKenney Signed-off-by: Mathieu Desnoyers --- rculfhash.c | 39 ++++++++++++++++++++++++++++++++++++++- urcu/rculfhash.h | 24 ++++++++++++++++++++---- 2 files changed, 58 insertions(+), 5 deletions(-) diff --git a/rculfhash.c b/rculfhash.c index ebefa92..f4187e7 100644 --- a/rculfhash.c +++ b/rculfhash.c @@ -222,15 +222,37 @@ /* Value of the end pointer. Should not interact with flags. */ #define END_VALUE NULL +/* + * ht_items_count: Split-counters counting the number of node addition + * and removal in the table. Only used if the CDS_LFHT_ACCOUNTING flag + * is set at hash table creation. + * + * These are free-running counters, never reset to zero. They count the + * number of add/remove, and trigger every (1 << COUNT_COMMIT_ORDER) + * operations to update the global counter. We choose a power-of-2 value + * for the trigger to deal with 32 or 64-bit overflow of the counter. + */ struct ht_items_count { unsigned long add, del; } __attribute__((aligned(CAA_CACHE_LINE_SIZE))); +/* + * rcu_level: Contains the per order-index-level dummy node table. The + * size of each dummy node table is half the number of hashes contained + * in this order (except for order 0). The minimum allocation size + * parameter allows combining the dummy node arrays of the lowermost + * levels to improve cache locality for small index orders. + */ struct rcu_level { /* Note: manually update allocation length when adding a field */ struct _cds_lfht_node nodes[0]; }; +/* + * rcu_table: Contains the size and desired new size if a resize + * operation is in progress, as well as the statically-sized array of + * rcu_level pointers. + */ struct rcu_table { unsigned long size; /* always a power of 2, shared (RCU) */ unsigned long resize_target; @@ -238,6 +260,11 @@ struct rcu_table { struct rcu_level *tbl[MAX_TABLE_ORDER]; }; +/* + * cds_lfht: Top-level data structure representing a lock-free hash + * table. Defined in the implementation file to make it be an opaque + * cookie to users. + */ struct cds_lfht { struct rcu_table t; cds_lfht_hash_fct hash_fct; @@ -269,11 +296,20 @@ struct cds_lfht { struct ht_items_count *split_count; /* split item count */ }; +/* + * rcu_resize_work: Contains arguments passed to RCU worker thread + * responsible for performing lazy resize. + */ struct rcu_resize_work { struct rcu_head head; struct cds_lfht *ht; }; +/* + * partition_resize_work: Contains arguments passed to worker threads + * executing the hash table resize on partitions of the hash table + * assigned to each processor's worker thread. + */ struct partition_resize_work { pthread_t thread_id; struct cds_lfht *ht; @@ -1381,9 +1417,10 @@ void cds_lfht_lookup(struct cds_lfht *ht, void *key, size_t key_len, break; } next = rcu_dereference(node->p.next); + assert(node == clear_flag(node)); if (likely(!is_removed(next)) && !is_dummy(next) - && clear_flag(node)->p.reverse_hash == reverse_hash + && node->p.reverse_hash == reverse_hash && likely(!ht->compare_fct(node->key, node->key_len, key, key_len))) { break; } diff --git a/urcu/rculfhash.h b/urcu/rculfhash.h index 9b96104..008b1d4 100644 --- a/urcu/rculfhash.h +++ b/urcu/rculfhash.h @@ -37,12 +37,22 @@ extern "C" { * 4-bytes boundaries because the two lower bits are used as flags. */ +/* + * _cds_lfht_node: Contains the internal pointers and reverse-hash + * value required for lookup and traversal of the hash table. + */ struct _cds_lfht_node { struct cds_lfht_node *next; /* ptr | DUMMY_FLAG | REMOVED_FLAG */ unsigned long reverse_hash; } __attribute__((aligned(4))); /* + * cds_lfht_node: Contains the full key and length required to check for + * an actual match, and also contains an rcu_head structure that is used + * by RCU to track a node through a given RCU grace period. There is an + * instance of _cds_lfht_node enclosed as a field within each + * _cds_lfht_node structure. + * * struct cds_lfht_node can be embedded into a structure (as a field). * caa_container_of() can be used to get the structure from the struct * cds_lfht_node after a lookup. @@ -56,6 +66,7 @@ struct cds_lfht_node { struct rcu_head head; }; +/* cds_lfht_iter: Used to track state while traversing a hash chain. */ struct cds_lfht_iter { struct cds_lfht_node *node, *next; }; @@ -163,7 +174,8 @@ struct cds_lfht *cds_lfht_new(cds_lfht_hash_fct hash_fct, * @ht: the hash table to destroy. * @attr: (output) resize worker thread attributes, as received by cds_lfht_new. * The caller will typically want to free this pointer if dynamically - * allocated. + * allocated. The attr point can be NULL if the caller does not + * need to be informed of the value passed to cds_lfht_new(). * * Return 0 on success, negative error value on error. * Threads calling this API need to be registered RCU read-side threads. @@ -172,15 +184,19 @@ int cds_lfht_destroy(struct cds_lfht *ht, pthread_attr_t **attr); /* * cds_lfht_count_nodes - count the number of nodes in the hash table. - * + * @ht: the hash table. + * @split_count_before: Sample the node count split-counter before traversal. + * @count: Traverse the hash table, count the number of nodes observed. + * @removed: Number of logically removed nodes observed during traversal. + * @split_count_after: Sample the node count split-counter after traversal. * Call with rcu_read_lock held. * Threads calling this API need to be registered RCU read-side threads. */ void cds_lfht_count_nodes(struct cds_lfht *ht, - long *approx_before, + long *split_count_before, unsigned long *count, unsigned long *removed, - long *approx_after); + long *split_count_after); /* * cds_lfht_lookup - lookup a node by key. -- 2.34.1