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