* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*
- * Include this file _after_ including your URCU flavor.
+ * For use with URCU_API_MAP (API mapping of liburcu), include this file
+ * _after_ including your URCU flavor.
*/
+#include <urcu/config.h>
#include <stdint.h>
+#include <pthread.h>
#include <urcu/compiler.h>
-#include <urcu-call-rcu.h>
-#include <urcu-flavor.h>
#ifdef __cplusplus
extern "C" {
#endif
+struct cds_lfht;
+
/*
* cds_lfht_node: Contains the next pointers and reverse-hash
* value required for lookup and traversal of the hash table.
/* cds_lfht_iter: Used to track state while traversing a hash chain. */
struct cds_lfht_iter {
struct cds_lfht_node *node, *next;
+ /*
+ * For debugging purposes, build both API users and rculfhash
+ * library with CDS_LFHT_ITER_DEBUG defined. This enables extra
+ * consistency checks for calls to a cds_lfht_next() or
+ * cds_lfht_next_duplicate() after the iterator has been
+ * re-purposed to iterate on a different hash table. This is a
+ * common programming mistake when performing hash table lookup
+ * nested in a hash table traversal.
+ */
+#ifdef CONFIG_CDS_LFHT_ITER_DEBUG
+ struct cds_lfht *lfht;
+#endif
};
static inline
return iter->node;
}
-struct cds_lfht;
+struct rcu_flavor_struct;
/*
* Caution !
* (detection of memory corruption).
*/
static inline
-void cds_lfht_node_init(struct cds_lfht_node *node)
+void cds_lfht_node_init(struct cds_lfht_node *node __attribute__((unused)))
{
}
+/*
+ * cds_lfht_node_init_deleted - initialize a hash table node to "removed" state
+ * @node: the node to initialize.
+ *
+ * Initialize the node such that cds_lfht_is_node_deleted() can be used
+ * on the node before it is added to a hash table.
+ */
+extern
+void cds_lfht_node_init_deleted(struct cds_lfht_node *node);
+
/*
* Hash table creation flags.
*/
const struct rcu_flavor_struct *flavor,
pthread_attr_t *attr);
+/*
+ * cds_lfht_new_flavor - allocate a hash table tied to a RCU flavor.
+ * @init_size: number of buckets to allocate initially. Must be power of two.
+ * @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, 0 is accepted, means
+ * "infinite")
+ * @flavor: flavor of liburcu to use to synchronize the hash table
+ * @flags: hash table creation flags (can be combined with bitwise or: '|').
+ * 0: no flags.
+ * CDS_LFHT_AUTO_RESIZE: automatically resize hash table.
+ * CDS_LFHT_ACCOUNTING: count the number of node addition
+ * and removal in the table
+ * @attr: optional resize worker thread attributes. NULL for default.
+ *
+ * Return NULL on error.
+ * Note: the RCU flavor must be already included before the hash table header.
+ *
+ * The programmer is responsible for ensuring that resize operation has a
+ * priority equal to hash table updater threads. It should be performed by
+ * specifying the appropriate priority in the pthread "attr" argument, and,
+ * for CDS_LFHT_AUTO_RESIZE, by ensuring that call_rcu worker threads also have
+ * this priority level. Having lower priority for call_rcu and resize threads
+ * does not pose any correctness issue, but the resize operations could be
+ * starved by updates, thus leading to long hash table bucket chains.
+ * Threads calling cds_lfht_new are NOT required to be registered RCU
+ * read-side threads. It can be called very early. (e.g. before RCU is
+ * initialized)
+ */
+static inline
+struct cds_lfht *cds_lfht_new_flavor(unsigned long init_size,
+ unsigned long min_nr_alloc_buckets,
+ unsigned long max_nr_buckets,
+ int flags,
+ const struct rcu_flavor_struct *flavor,
+ pthread_attr_t *attr)
+{
+ return _cds_lfht_new(init_size, min_nr_alloc_buckets, max_nr_buckets,
+ flags, NULL, flavor, attr);
+}
+
+
+#ifdef URCU_API_MAP
/*
* cds_lfht_new - allocate a hash table.
* @init_size: number of buckets to allocate initially. Must be power of two.
return _cds_lfht_new(init_size, min_nr_alloc_buckets, max_nr_buckets,
flags, NULL, &rcu_flavor, attr);
}
+#endif /* URCU_API_MAP */
/*
* cds_lfht_destroy - destroy a hash table.
* 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.
- * 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.
+ *
+ * Prior to liburcu 0.10:
+ * - 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.
+ *
+ * Starting from liburcu 0.10, rculfhash implements its own worker
+ * thread to handle resize operations, which removes the above RCU
+ * read-side critical section requirement on cds_lfht_destroy.
*/
extern
int cds_lfht_destroy(struct cds_lfht *ht, pthread_attr_t **attr);
* This function does not issue any memory barrier.
*/
extern
-int cds_lfht_is_node_deleted(struct cds_lfht_node *node);
+int cds_lfht_is_node_deleted(const struct cds_lfht_node *node);
/*
* cds_lfht_resize - Force a hash table resize
cds_lfht_next_duplicate(ht, match, key, iter), \
node = cds_lfht_iter_get_node(iter))
+#define cds_lfht_entry(ptr, type, member) \
+ caa_container_of_check_null(ptr, type, member)
+
#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); \
- cds_lfht_iter_get_node(iter) != NULL; \
+ pos = cds_lfht_entry(cds_lfht_iter_get_node(iter), \
+ __typeof__(*(pos)), member); \
+ pos != NULL; \
cds_lfht_next(ht, iter), \
- pos = caa_container_of(cds_lfht_iter_get_node(iter), \
- __typeof__(*(pos)), member))
+ pos = cds_lfht_entry(cds_lfht_iter_get_node(iter), \
+ __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); \
- cds_lfht_iter_get_node(iter) != NULL; \
+ pos = cds_lfht_entry(cds_lfht_iter_get_node(iter), \
+ __typeof__(*(pos)), member); \
+ pos != NULL; \
cds_lfht_next_duplicate(ht, match, key, iter), \
- pos = caa_container_of(cds_lfht_iter_get_node(iter), \
- __typeof__(*(pos)), member))
+ pos = cds_lfht_entry(cds_lfht_iter_get_node(iter), \
+ __typeof__(*(pos)), member))
#ifdef __cplusplus
}