ck_ht_init (3) - Linux Manuals

ck_ht_init: initialize a hash table

NAME

ck_ht_init - initialize a hash table

LIBRARY

Concurrency Kit (libck, -lck)

SYNOPSIS

In ck_ht.h Ft typedef void Fn ck_ht_hash_cb_t ck_ht_hash_t *h const void *key size_t key_length uint64_t seed Ft bool Fn 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 Fn ck_ht_init function initializes the hash table pointed to by the Fa ht pointer.

The argument Fa mode specifies the type of key-value pairs to be stored in the hash table. The value of Fa 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_empty3, ck_ht_entry_key3, ck_ht_entry_key_length3, ck_ht_entry_value3, and ck_ht_entry_set3 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_empty3, ck_ht_entry_key_direct3, ck_ht_entry_value_direct3 and ck_ht_entry_set_direct3 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 Fa 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_hash3). A user-specified hash function takes four arguments. The Fa h argument is a pointer to a hash value object. The hash function is expected to update the Fa value object of type Fa uint64_t contained with-in the object pointed to by Fa h . The Fa key argument is a pointer to a key, the Fa key_length argument is the length of the key and the Fa seed argument is the initial seed associated with the hash table. This initial seed is specified by the user in ck_ht_init3.

The Fa allocator argument is a pointer to a structure containing Fa malloc and Fa free function pointers which respectively define the memory allocation and destruction functions to be used by the hash table being initialized.

The argument Fa 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 Fa capacity specifies.

The argument Fa 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 Fn ck_ht_init returns a value of true and otherwise returns a value of false to indicate an error.

ERRORS

The behavior of Fn ck_ht_init is undefined if Fa ht is not a pointer to a ck_ht_t object.