DragonFly On-Line Manual Pages

CK_RHS_INIT(3)        DragonFly Library Functions Manual        CK_RHS_INIT(3)

NAME
     ck_rhs_init - initialize a hash set

LIBRARY
     Concurrency Kit (libck, -lck)

SYNOPSIS
     #include <ck_rhs.h>

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

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

     bool
     ck_rhs_init(ck_rhs_t *hs, unsigned int mode,
         ck_rhs_hash_cb_t *hash_function, ck_rhs_compare_cb_t *compare,
         struct ck_malloc *allocator, unsigned long capacity,
         unsigned long seed);

DESCRIPTION
     The ck_rhs_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_RHS_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_RHS_MODE_DIRECT
             The hash set is meant to directly store key values and that all
             bits of the key are used to encode values.

     CK_RHS_MODE_READ_MOSTLY
             Optimize read operations over put/delete.

     The concurrent access model is specified by:

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

     CK_RHS_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:

     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_rhs_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_rhs_init() returns a value of true and
     otherwise returns a value of false to indicate an error.

ERRORS
     The behavior of ck_rhs_init() is undefined if hs is not a pointer to a
     ck_rhs_t object.

SEE ALSO
     ck_rhs_move(3), ck_rhs_destroy(3), CK_RHS_HASH(3),
     ck_rhs_iterator_init(3), ck_rhs_next(3), ck_rhs_get(3), ck_rhs_put(3),
     ck_rhs_put_unique(3), ck_rhs_set(3), ck_rhs_fas(3), ck_rhs_remove(3),
     ck_rhs_grow(3), ck_rhs_rebuild(3), ck_rhs_gc(3), ck_rhs_count(3),
     ck_rhs_reset(3), ck_rhs_reset_size(3), ck_rhs_stat(3)

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

                              September 17, 2012