CK_HT_SET_SPMC(3)

💖 ck_ht_set_spmc(3) — the "put this in the table bestie" page 💖

okay so welcome to ck_ht_set_spmc, a manual page from the Concurrency Kit besties, and it does exactly one thing: it stores a key-value pair into a hash table. that's it. that's the whole vibe. and it does it while other people are reading the table at the same time, which is the iconic part.

✨ LIBRARY ✨

Concurrency Kit — link it with libck, so pop -lck on your link line. no cap.

🌸 SYNOPSIS 🌸

#include <ck_ht.h>

bool
ck_ht_set_spmc(ck_ht_t *ht, ck_ht_hash_t h, ck_ht_entry_t *entry);

🦋 DESCRIPTION 🦋

so the way that ck_ht_set_spmc() works is: it takes the key-value pair you packed into the entry argument and stores it in the hash table that ht points to. and here's the little detail that matters — the key inside entry is expected to already have the hash value you're passing in as h. like, you don't get to just hand it a random number, the hash has to match the key fr fr.

now, depending on how your table was born:

• if ht was created with CK_HT_MODE_BYTESTRING, then entry must have been initialized with the ck_ht_entry_set(3) function. that's the one.
• if ht was created with CK_HT_MODE_DIRECT, then entry must have been initialized with the ck_ht_entry_set_direct(3) function instead. different function, different mode, don't mix them 💅

and the hash h has to match the mode too:

• it's expected that h was initialized with ck_ht_hash(3) if ht was created with CK_HT_MODE_BYTESTRING.
• if ht was initialized with CK_HT_MODE_DIRECT then it's expected that h was initialized with the ck_ht_hash_direct(3) function.

okay now the fun part, the actual update semantics 🎀:

• if the call to ck_ht_set_spmc() was successful, then the key-value pair sitting in entry will now contain the previous key-value pair that was associated with the key originally contained in the entry argument. so you hand over your new pair and the old one comes back to you in the same struct. it's giving swap, it's giving trade, it's giving main character energy.
• if the operation was unsuccessful, then entry is left unmodified. untouched. pristine. not a single byte moved.

and the headline feature: this function is safe to call in the presence of concurrent ck_ht_get_spmc operations. yes bestie, readers can be vibing in there while you write. that's the SPMC of it all, iykyk 🔥

👑 RETURN VALUES 👑

• on a successful completion, ck_ht_set_spmc() returns true.
• otherwise it returns false on failure. that's it, that's the boolean 💀

💀 ERRORS 💀

🚨 behaviour is undefined if entry or ht are uninitialized. undefined. not "a little weird", not "it'll probably be fine" — undefined behaviour. do not pass garbage pointers and expect mercy, bestie. initialize your stuff first. 🙈

the function will return false if the hash table was required to be grown but failed while attempting to grow. so like, the table needed more room and couldn't get it, and instead of doing something unhinged it just says false. very demure, very mindful.

🫶 SEE ALSO 🫶

the whole friend group, go say hi:

• ck_ht_stat(3)
• ck_ht_init(3)
• ck_ht_destroy(3)
• ck_ht_hash(3)
• ck_ht_hash_direct(3)
• ck_ht_put_spmc(3)
• ck_ht_gc(3)
• ck_ht_get_spmc(3)
• ck_ht_grow_spmc(3)
• ck_ht_remove_spmc(3)
• ck_ht_reset_spmc(3)
• ck_ht_reset_size_spmc(3)
• ck_ht_count(3)
• ck_ht_entry_empty(3)
• ck_ht_entry_key_set(3)
• ck_ht_entry_key_set_direct(3)
• ck_ht_entry_key(3)
• ck_ht_entry_key_length(3)
• ck_ht_entry_value(3)
• ck_ht_entry_set(3)
• ck_ht_entry_set_direct(3)
• ck_ht_entry_key_direct(3)
• ck_ht_entry_value_direct(3)
• ck_ht_iterator_init(3)
• ck_ht_next(3)

and if you want even more lore, it's all waiting at http://concurrencykit.org/ ⭐

and that's the page!! 💖 this one is dated March 29, 2012 and it lives at CK_HT_SET_SPMC(3) in the Concurrency Kit set — ily, go write some lock-free code responsibly, and remember: initialize your entries before you talk to me 🎀✨🦋