NAME¶
ck_ht_init —
initialize a hash table
LIBRARY¶
Concurrency Kit (libck, -lck)
SYNOPSIS¶
#include
<ck_ht.h>
typedef void
ck_ht_hash_cb_t(
ck_ht_hash_t
*h,
const void
*key,
size_t
key_length,
uint64_t seed);
bool
ck_ht_init(
ck_ht_t
*ht,
enum
ck_ht_mode mode,
ck_ht_hash_cb_t
*hash_function,
struct ck_malloc
*allocator,
uint64_t
capacity,
uint64_t seed);
DESCRIPTION¶
The
ck_ht_init() function initializes the
hash table pointed to by the
ht pointer.
The argument
mode specifies the type of
key-value pairs to be stored in the hash table. The value of
mode may be one of:
- CK_HT_MODE_BYTESTRING
- The hash table is meant to store key-value pointers where key is a region
of memory that is up to 65536 bytes long. This pointer will be
dereferenced during hash table operations for key comparison. Entries of
this hash table are expected to be interacted with using the
ck_ht_entry_empty(3),
ck_ht_entry_key(3),
ck_ht_entry_key_length(3),
ck_ht_entry_value(3), and
ck_ht_entry_set(3) functions. Attempting a
hash table operation with a key of value NULL or (void *)UINTPTR_MAX will
result in undefined behavior.
- CK_HT_MODE_DIRECT
- The hash table is meant to store key-value pointers where the key is of
fixed width field compatible with the uintptr_t type. The key will be
directly compared with other keys for equality. Entries of this hash table
are expected to be interacted with using the
ck_ht_entry_empty(3),
ck_ht_entry_key_direct(3),
ck_ht_entry_value_direct(3) and
ck_entry_set_direct(3) functions. Attempting
a hash table operation with a key of value of 0 or UINTPTR_MAX will result
in undefined behavior.
In addition to this, the user may bitwise OR the mode flag with
CK_HT_WORKLOAD_DELETE to indicate that the hash table will have to handle a
delete heavy workload, in which case stronger bounds on latency can be
provided at the cost of approximately 13% higher memory usage. The argument
hash_function is a pointer to a
user-specified hash function. It is optional, if
NULL is specified, then the default hash
function implementation will be used (
ck_ht_hash(3) ). A user-specified hash function
takes four arguments. The
h argument is a
pointer to a hash value object. The hash function is expected to update the
value object of type
uint64_t contained with-in the object pointed
to by
h. The
key argument is a pointer to a key, the
key_length argument is the length of the key
and the
seed argument is the initial seed
associated with the hash table. This initial seed is specified by the user in
ck_ht_init(3).
The
allocator argument is a pointer to a
structure containing
malloc and
free function pointers which respectively
define the memory allocation and destruction functions to be used by the hash
table being initialized.
The argument
capacity represents the initial
number of key-value pairs the hash table is expected to contain. This argument
is simply a hint and the underlying implementation is free to allocate more or
less memory than necessary to contain the number of entries
capacity specifies.
The argument
seed specifies the initial seed
used by the underlying hash function. The user is free to choose a value of
their choice.
The hash table is safe to access by multiple readers in the presence of one
concurrent writer. Behavior is undefined in the presence of concurrent
writers.
RETURN VALUES¶
Upon successful completion
ck_ht_init()
returns a value of
true and otherwise
returns a value of
false to indicate an
error.
ERRORS¶
The behavior of
ck_ht_init() is undefined if
ht is not a pointer to a ck_ht_t object.
SEE ALSO¶
ck_ht_stat(3),
ck_ht_destroy(3),
ck_ht_hash(3),
ck_ht_hash_direct(3),
ck_ht_set_spmc(3),
ck_ht_put_spmc(3),
ck_ht_gc(3),
ck_ht_get_spmc(3),
ck_ht_grow_spmc(3),
ck_ht_remove_spmc(3),
ck_ht_reset_spmc(3),
ck_ht_reset_size_spmc(3),
ck_ht_count(3),
ck_ht_entry_empty(3),
ck_ht_entry_key_set(3),
ck_ht_entry_key_set_direct(3),
ck_ht_entry_key(3),
ck_ht_entry_key_length(3),
ck_ht_entry_value(3),
ck_ht_entry_set(3),
ck_ht_entry_set_direct(3),
ck_ht_entry_key_direct(3),
ck_ht_entry_value_direct(3),
ck_ht_iterator_init(3),
ck_ht_next(3)
Additional information available at
http://concurrencykit.org/
