1CK_HS_INIT(3)            BSD Library Functions Manual            CK_HS_INIT(3)
2

NAME

4     ck_hs_init — initialize a hash set
5

LIBRARY

7     Concurrency Kit (libck, -lck)
8

SYNOPSIS

10     #include <ck_hs.h>
11
12     typedef unsigned long
13     ck_hs_hash_cb_t(const void *key, unsigned long seed);
14
15     typedef bool
16     ck_hs_compare_cb_t(const void *c1, const void *c2);
17
18     bool
19     ck_hs_init(ck_hs_t *hs, unsigned int mode,
20         ck_hs_hash_cb_t *hash_function, ck_hs_compare_cb_t *compare,
21         struct ck_malloc *allocator, unsigned long capacity,
22         unsigned long seed);
23

DESCRIPTION

25     The ck_hs_init() function initializes the hash set pointed to by the hs
26     pointer.
27
28     The argument mode specifies the type of key-value pairs to be stored in
29     the hash set as well as the expected concurrent access model.  The value
30     of mode consists of a bitfield of one of the following:
31
32     CK_HS_MODE_OBJECT
33             The hash set is meant to store pointers to objects. This provides
34             a hint that only CK_MD_VMA_BITS are necessary to encode the key
35             argument. Any unused pointer bits are leveraged for internal
36             optimizations.
37
38     CK_HS_MODE_DIRECT
39             The hash set is meant to directly store key values and that all
40             bits of the key are used to encode values.
41
42     The concurrent access model is specified by:
43
44     CK_HS_MODE_SPMC
45             The hash set should allow for concurrent readers in the presence
46             of a single writer.
47
48     CK_HS_MODE_MPMC
49             The hash set should allow for concurrent readers in the presence
50             of concurrent writers. This is currently unsupported.
51
52     The developer is free to specify additional workload hints.  These hints
53     are one of:
54
55     CK_HS_MODE_DELETE
56             The hash set is expected to have a delete-heavy workload.  At the
57             cost of approximately 13% increased memory usage, allow for
58             stronger per-slot probe bounds to combat the effects of tombstone
59             accumulation.
60
61     The argument hash_function is a mandatory pointer to a user-specified
62     hash function.  A user-specified hash function takes two arguments. The
63     key argument is a pointer to a key. The seed argument is the initial seed
64     associated with the hash set.  This initial seed is specified by the user
65     in ck_hs_init(3).
66
67     The compare argument is an optional pointer to a user-specified key com‐
68     parison function. If NULL is specified in this argument, then pointer
69     equality will be used to determine key equality. A user-specified compar‐
70     ison function takes two arguments representing pointers to the objects
71     being compared for equality. It is expected to return true if the keys
72     are of equal value and false otherwise.
73
74     The allocator argument is a pointer to a structure containing malloc and
75     free function pointers which respectively define the memory allocation
76     and destruction functions to be used by the hash set being initialized.
77
78     The argument capacity represents the initial number of keys the hash set
79     is expected to contain. This argument is simply a hint and the underlying
80     implementation is free to allocate more or less memory than necessary to
81     contain the number of entries capacity specifies.
82
83     The argument seed specifies the initial seed used by the underlying hash
84     function.  The user is free to choose a value of their choice.
85

RETURN VALUES

87     Upon successful completion ck_hs_init() returns a value of true and oth‐
88     erwise returns a value of false to indicate an error.
89

ERRORS

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

SEE ALSO

95     ck_hs_move(3), ck_hs_destroy(3), CK_HS_HASH(3), ck_hs_iterator_init(3),
96     ck_hs_next(3), ck_hs_get(3), ck_hs_put(3), ck_hs_put_unique(3),
97     ck_hs_set(3), ck_hs_fas(3), ck_hs_remove(3), ck_hs_grow(3),
98     ck_hs_rebuild(3), ck_hs_gc(3), ck_hs_count(3), ck_hs_reset(3),
99     ck_hs_reset_size(3), ck_hs_stat(3)
100
101     Additional information available at http://concurrencykit.org/
102
103                              September 17, 2012
Impressum