CK_RHS_INIT(3)

🌸 NAME 🌸

ck_rhs_init — initialize a hash set 💖

It's giving "welcome to the party, let's set up your hash set bestie". This is CK_RHS_INIT(3), and yeah, she's iconic.

---

📚 LIBRARY 📚

Concurrency Kit (libck, -lck) — the whole squad lives here 🫶

---

✨ 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 💅

So ck_rhs_init() initializes the hash set that hs is pointing at. That's the whole gig. Main character behaviour, honestly.

The mode argument

mode tells you two things at once: what kind of key-value pairs are getting stored, and what concurrent access model you're expecting. It's a bitfield, and it takes one of these:

• CK_RHS_MODE_OBJECT — the hash set is here to store pointers to objects. It's basically a lil hint that only CK_MD_VMA_BITS are needed to encode the key argument, and any unused pointer bits get repurposed for internal optimizations ✨
• CK_RHS_MODE_DIRECT — the hash set stores key values directly, and every single bit of the key is used to encode values. No bits left behind, periodt.
• CK_RHS_MODE_READ_MOSTLY — optimizes read operations over put/delete. For the girlies who mostly just look 👀

The concurrent access model

You pick one of these:

• CK_RHS_MODE_SPMC — the hash set should allow concurrent readers when there's a single writer. One pen, many eyeballs, love that for us.
• CK_RHS_MODE_MPMC — the hash set should allow concurrent readers when there are concurrent writers. And uhh… heads up bestie: this is currently unsupported. 🚨

The developer is free to specify additional workload hints. These hints are one of:

(that's it. that's the list. it just ends. we don't make the rules 💀)

The hash_function argument

hash_function is a mandatory pointer to a user-specified hash function — no skipping this one, fr fr. Your hash function takes two arguments:

• key — a pointer to a key.
• seed — the initial seed associated with the hash set.

That initial seed is the one the user specifies in ck_rhs_init(3). Full circle, cute.

The compare argument

compare is an optional pointer to a user-specified key comparison function. If you pass NULL here, then pointer equality is what decides key equality. Chill, low-effort, valid.

Your custom comparison function takes two arguments — pointers to the objects being compared for equality — and it's expected to return true if the keys are of equal value, and false otherwise. Yes/no, slay/not slay.

The allocator argument

allocator is a pointer to a struct holding malloc and free function pointers, which define the memory allocation and destruction functions the hash set being initialized is gonna use. Your memory, your rules 💖

The capacity argument

capacity is 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 hold the number of entries capacity says. So don't get attached to the exact number, bestie.

The seed argument

seed is the initial seed used by the underlying hash function. Pick whatever value you want — the user is free to choose a value of their choice. Go wild 🌈

---

🎀 RETURN VALUES 🎀

• If it works out: ck_rhs_init() returns true 🥳
• If it does not: it returns false, which means error. Sad girl hours 😭

---

🚨 ERRORS 🚨

The behavior of ck_rhs_init() is undefined if hs is not a pointer to a ck_rhs_t object. Not undefined-ish. Not "probably fine". Undefined. Do not test this. I'm literally begging 🙈

---

👑 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/ — go read, it's giving resources 💅

---

That's the whole page, bestie ✨ This one came from the Concurrency Kit source, dated September 17, 2012, and it lives at CK_RHS_INIT(3). Go forth and initialize something gorgeous 💖🎀🦋