NAME

       ck_hs_init — initialize a hash set

LIBRARY

       Concurrency Kit (libck, -lck)

SYNOPSIS

       #include <ck_hs.h>

       typedef unsigned long
       ck_hs_hash_cb_t(const void *key, unsigned long seed);

       typedef bool
       ck_hs_compare_cb_t(const void *c1, const void *c2);

       bool
       ck_hs_init(ck_hs_t  *hs,  unsigned int mode, ck_hs_hash_cb_t *hash_function, ck_hs_compare_cb_t *compare,
           struct ck_malloc *allocator, unsigned long capacity, unsigned long seed);

DESCRIPTION

       The ck_hs_init() function initializes the hash set pointed to by the hs pointer.

       The argument mode specifies the type of key-value pairs to be stored in the  hash  set  as  well  as  the
       expected concurrent access model.  The value of mode consists of a bitfield of one of the following:

       CK_HS_MODE_OBJECT
               The hash set is meant to store pointers to objects. This provides a hint that only CK_MD_VMA_BITS
               are  necessary  to  encode  the  key argument. Any unused pointer bits are leveraged for internal
               optimizations.

       CK_HS_MODE_DIRECT
               The hash set is meant to directly store key values and that all bits  of  the  key  are  used  to
               encode values.

       The concurrent access model is specified by:

       CK_HS_MODE_SPMC
               The hash set should allow for concurrent readers in the presence of a single writer.

       CK_HS_MODE_MPMC
               The  hash  set should allow for concurrent readers in the presence of concurrent writers. This is
               currently unsupported.

       The developer is free to specify additional workload hints.  These hints are one of:

       CK_HS_MODE_DELETE
               The hash set is expected to have a delete-heavy workload.   At  the  cost  of  approximately  13%
               increased  memory  usage,  allow  for  stronger  per-slot  probe  bounds to combat the effects of
               tombstone accumulation.

       The argument hash_function is a mandatory pointer to a user-specified hash  function.   A  user-specified
       hash  function  takes  two  arguments.  The  key argument is a pointer to a key. The seed argument is the
       initial seed associated with the hash set.  This initial seed is specified by the user in ck_hs_init(3).

       The compare argument is an optional pointer to a user-specified  key  comparison  function.  If  NULL  is
       specified  in  this  argument,  then  pointer  equality  will  be used to determine key equality. A user-
       specified comparison function takes two arguments representing pointers to the objects being compared for
       equality. It is expected to return true if the keys are of equal value and false otherwise.

       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 set being
       initialized.

       The argument capacity represents the initial number of keys the hash set 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.

RETURN VALUES

       Upon successful completion ck_hs_init() returns a value of true and otherwise returns a value of false to
       indicate an error.

ERRORS

       The behavior of ck_hs_init() is undefined if hs is not a pointer to a ck_hs_t object.

SEE ALSO

       ck_hs_move(3),  ck_hs_destroy(3),  CK_HS_HASH(3),  ck_hs_iterator_init(3),  ck_hs_next(3),  ck_hs_get(3),
       ck_hs_put(3),   ck_hs_put_unique(3),   ck_hs_set(3),   ck_hs_fas(3),   ck_hs_remove(3),    ck_hs_grow(3),
       ck_hs_rebuild(3), ck_hs_gc(3), ck_hs_count(3), ck_hs_reset(3), ck_hs_reset_size(3), ck_hs_stat(3)

       Additional information available at http://concurrencykit.org/

                                               September 17, 2012                                  CK_HS_INIT(3)