--- name: "ck_ht_init" section: "3" platform: "linux" package: "libck-dev" version: "0.7.2-6" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/ck_ht_init" --- # ck\_ht\_init(3) initialize a hash table ## NAME **ck\_ht\_init** – initialize a hash table ## LIBRARY Concurrency Kit (libck, -lck) ## SYNOPSIS **#include \** *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_empty/3.md), [ck\_ht\_entry\_key(3)](/ck_ht_entry_key/3.md), [ck\_ht\_entry\_key\_length(3)](/ck_ht_entry_key_length/3.md), [ck\_ht\_entry\_value(3)](/ck_ht_entry_value/3.md), and [ck\_ht\_entry\_set(3)](/ck_ht_entry_set/3.md) 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_empty/3.md), [ck\_ht\_entry\_key\_direct(3)](/ck_ht_entry_key_direct/3.md), [ck\_ht\_entry\_value\_direct(3)](/ck_ht_entry_value_direct/3.md) and [ck\_ht\_entry\_set\_direct(3)](/ck_ht_entry_set_direct/3.md) 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)](/ck_ht_hash/3.md) ). 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)](/ck_ht_init/3.md). 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_stat/3.md), [ck\_ht\_destroy(3)](/ck_ht_destroy/3.md), [ck\_ht\_hash(3)](/ck_ht_hash/3.md), [ck\_ht\_hash\_direct(3)](/ck_ht_hash_direct/3.md), [ck\_ht\_set\_spmc(3)](/ck_ht_set_spmc/3.md), [ck\_ht\_put\_spmc(3)](/ck_ht_put_spmc/3.md), [ck\_ht\_gc(3)](/ck_ht_gc/3.md), [ck\_ht\_get\_spmc(3)](/ck_ht_get_spmc/3.md), [ck\_ht\_grow\_spmc(3)](/ck_ht_grow_spmc/3.md), [ck\_ht\_remove\_spmc(3)](/ck_ht_remove_spmc/3.md), [ck\_ht\_reset\_spmc(3)](/ck_ht_reset_spmc/3.md), [ck\_ht\_reset\_size\_spmc(3)](/ck_ht_reset_size_spmc/3.md), [ck\_ht\_count(3)](/ck_ht_count/3.md), [ck\_ht\_entry\_empty(3)](/ck_ht_entry_empty/3.md), [ck\_ht\_entry\_key\_set(3)](/ck_ht_entry_key_set/3.md), [ck\_ht\_entry\_key\_set\_direct(3)](/ck_ht_entry_key_set_direct/3.md), [ck\_ht\_entry\_key(3)](/ck_ht_entry_key/3.md), [ck\_ht\_entry\_key\_length(3)](/ck_ht_entry_key_length/3.md), [ck\_ht\_entry\_value(3)](/ck_ht_entry_value/3.md), [ck\_ht\_entry\_set(3)](/ck_ht_entry_set/3.md), [ck\_ht\_entry\_set\_direct(3)](/ck_ht_entry_set_direct/3.md), [ck\_ht\_entry\_key\_direct(3)](/ck_ht_entry_key_direct/3.md), [ck\_ht\_entry\_value\_direct(3)](/ck_ht_entry_value_direct/3.md), [ck\_ht\_iterator\_init(3)](/ck_ht_iterator_init/3.md), [ck\_ht\_next(3)](/ck_ht_next/3.md) Additional information available at http://concurrencykit.org/