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_ht_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/

                                          March 28, 2012