1CK_HT_INIT(3)            BSD Library Functions Manual            CK_HT_INIT(3)
2

NAME

4     ck_ht_init — initialize a hash table
5

LIBRARY

7     Concurrency Kit (libck, -lck)
8

SYNOPSIS

10     #include <ck_ht.h>
11
12     typedef void
13     ck_ht_hash_cb_t(ck_ht_hash_t *h, const void *key, size_t key_length,
14         uint64_t seed);
15
16     bool
17     ck_ht_init(ck_ht_t *ht, enum ck_ht_mode mode,
18         ck_ht_hash_cb_t *hash_function, struct ck_malloc *allocator,
19         uint64_t capacity, uint64_t seed);
20

DESCRIPTION

22     The ck_ht_init() function initializes the hash table pointed to by the ht
23     pointer.
24
25     The argument mode specifies the type of key-value pairs to be stored in
26     the hash table. The value of mode may be one of:
27
28     CK_HT_MODE_BYTESTRING
29             The hash table is meant to store key-value pointers where key is
30             a region of memory that is up to 65536 bytes long.  This pointer
31             will be dereferenced during hash table operations for key compar‐
32             ison. Entries of this hash table are expected to be interacted
33             with using the ck_ht_entry_empty(3), ck_ht_entry_key(3),
34             ck_ht_entry_key_length(3), ck_ht_entry_value(3), and
35             ck_ht_entry_set(3) functions. Attempting a hash table operation
36             with a key of value NULL or (void *)UINTPTR_MAX will result in
37             undefined behavior.
38
39     CK_HT_MODE_DIRECT
40             The hash table is meant to store key-value pointers where the key
41             is of fixed width field compatible with the uintptr_t type. The
42             key will be directly compared with other keys for equality.
43             Entries of this hash table are expected to be interacted with
44             using the ck_ht_entry_empty(3), ck_ht_entry_key_direct(3),
45             ck_ht_entry_value_direct(3) and ck_ht_entry_set_direct(3) func‐
46             tions. Attempting a hash table operation with a key of value of 0
47             or UINTPTR_MAX will result in undefined behavior.
48
49     In addition to this, the user may bitwise OR the mode flag with
50     CK_HT_WORKLOAD_DELETE to indicate that the hash table will have to handle
51     a delete heavy workload, in which case stronger bounds on latency can be
52     provided at the cost of approximately 13% higher memory usage.  The argu‐
53     ment hash_function is a pointer to a user-specified hash function. It is
54     optional, if NULL is specified, then the default hash function implemen‐
55     tation will be used ( ck_ht_hash(3) ). A user-specified hash function
56     takes four arguments. The h argument is a pointer to a hash value object.
57     The hash function is expected to update the value object of type uint64_t
58     contained with-in the object pointed to by h.  The key argument is a
59     pointer to a key, the key_length argument is the length of the key and
60     the seed argument is the initial seed associated with the hash table.
61     This initial seed is specified by the user in ck_ht_init(3).
62
63     The allocator argument is a pointer to a structure containing malloc and
64     free function pointers which respectively define the memory allocation
65     and destruction functions to be used by the hash table being initialized.
66
67     The argument capacity represents the initial number of key-value pairs
68     the hash table is expected to contain. This argument is simply a hint and
69     the underlying implementation is free to allocate more or less memory
70     than necessary to contain the number of entries capacity specifies.
71
72     The argument seed specifies the initial seed used by the underlying hash
73     function.  The user is free to choose a value of their choice.
74
75     The hash table is safe to access by multiple readers in the presence of
76     one concurrent writer. Behavior is undefined in the presence of concur‐
77     rent writers.
78

RETURN VALUES

80     Upon successful completion ck_ht_init() returns a value of true and oth‐
81     erwise returns a value of false to indicate an error.
82

ERRORS

84     The behavior of ck_ht_init() is undefined if ht is not a pointer to a
85     ck_ht_t object.
86

SEE ALSO

88     ck_ht_stat(3), ck_ht_destroy(3), ck_ht_hash(3), ck_ht_hash_direct(3),
89     ck_ht_set_spmc(3), ck_ht_put_spmc(3), ck_ht_gc(3), ck_ht_get_spmc(3),
90     ck_ht_grow_spmc(3), ck_ht_remove_spmc(3), ck_ht_reset_spmc(3),
91     ck_ht_reset_size_spmc(3), ck_ht_count(3), ck_ht_entry_empty(3),
92     ck_ht_entry_key_set(3), ck_ht_entry_key_set_direct(3),
93     ck_ht_entry_key(3), ck_ht_entry_key_length(3), ck_ht_entry_value(3),
94     ck_ht_entry_set(3), ck_ht_entry_set_direct(3), ck_ht_entry_key_direct(3),
95     ck_ht_entry_value_direct(3), ck_ht_iterator_init(3), ck_ht_next(3)
96
97     Additional information available at http://concurrencykit.org/
98
99                                March 28, 2012