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/
