CK_HS_INIT(3)

💖 CK_HS_INIT(3) — the ck_hs_init manual, bestie edition 💖

okay so you're in the Concurrency Kit section of the manual (that's libck, link it with -lck), and today we're setting up a hash set. not reading from it, not writing to it — just birthing it. main character energy fr fr ✨

---

🌸 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);

like. look at her. she's gorgeous. 💅

---

🦋 DESCRIPTION 🦋

so ck_hs_init() initializes the hash set that hs is pointing at. that's it. that's the job. she sets it up and hands you back a bool. no cap.

🌈 the mode argument

mode tells us two things: what kind of key-value pairs you're storing, and what concurrent access model you expect. it's a bitfield, so you OR these together. let's go one by one because this is the part everyone skips and then gets confused about later 💀

key-value type vibes

• CK_HS_MODE_OBJECT — you're storing pointers to objects. this is a hint that only CK_MD_VMA_BITS are needed to encode the key argument, and any unused pointer bits get used for internal optimizations. little bit of free real estate, we love to see it. 👑
• CK_HS_MODE_DIRECT — you're storing key values directly, and all the bits of the key are used to encode values. no free bits, no shortcuts, just the key, raw and unfiltered.

concurrent access model, aka who's allowed in the group chat

• CK_HS_MODE_SPMC — concurrent readers, single writer. one person types, everyone else reads. very "one person holds the aux" energy. 🎧
• CK_HS_MODE_MPMC — concurrent readers and concurrent writers. > ⚠️ bestie this one is currently unsupported. don't do it. it's giving unfinished business. 😭

extra workload hints (optional, but cute)

• CK_HS_MODE_DELETE — you expect a delete-heavy workload. at the cost of approximately 13% increased memory usage, it allows for stronger per-slot probe bounds to combat the effects of tombstone accumulation. yeah, tombstones. spooky. but worth it if you delete a lot. 🪦✨

🎀 the hash_function argument

mandatory!! pointer to a user-specified hash function. it takes two args:

• key — a pointer to a key.
• seed — the initial seed associated with the hash set. and where does that seed come from? you. you give it in ck_hs_init(3). it's your seed, you chose it, own it. 🌱

💜 the compare argument

optional pointer to a user-specified key comparison function. if you pass NULL here, then pointer equality is what determines key equality. simple. iconic. if you do pass a function, it takes two arguments that are pointers to the objects being compared for equality, and it should return true if the keys are of equal value and false otherwise. that's the whole contract, no notes. 🫶

🧚 the allocator argument

a pointer to a struct containing malloc and free function pointers, which respectively define the memory allocation and destruction functions your hash set will use. you're in charge of the memory situation, we're just living in it.

⭐ the capacity argument

the initial number of keys the hash set is expected to contain. important: this is just a hint. the underlying implementation is free to allocate more or less memory than necessary to contain the number of entries capacity specifies. so don't be weird about it.

🌸 the seed argument

the initial seed used by the underlying hash function. the user is free to choose a value of their choice. that's you. choose. 🎲

---

✨ RETURN VALUES ✨

if it works, ck_hs_init() returns true. if it doesn't, it returns false to indicate an error. that's the whole story, short and sweet. 💖

---

🚨 ERRORS 🚨

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

read that again. not a warning. not a polite nudge. undefined behavior. pass her a real ck_hs_t or don't pass her anything at all. 😤

---

👀 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 info is available at http://concurrencykit.org/ — go read it, bestie, it's giving educational. 📚

---

okay that's the whole page!! this one's from Concurrency Kit, and the version we're looking at is dated September 17, 2012. love that for us. go init a hash set, you've got this 💅✨🦋