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                                    CK_HT_INIT(3)