CK_HS_FAS(3)

💖 CK_HS_FAS(3) 💖

okay bestie, so this is a page from the Concurrency Kit manual (that's libck, and you link it with -lck — noted, remembered, slaying). It's all about one lil function that does a fetch-and-store on a hash set. Iconic behavior. Let's get into it ✨

🌸 LIBRARY 🌸

Concurrency Kit (libck, link it with -lck) 🫶

✨ SYNOPSIS ✨

#include <ck_hs.h>

bool
ck_hs_fas(ck_hs_t *hs, unsigned long hash, const void *key,
    void **previous);

🦋 DESCRIPTION 🦋

So the ck_hs_fas(3) function does a lil fetch and store, no cap. It takes the key you point at with the key argument and stores it into the hash set that hs points to. 💅

Now, the key in key is expected to already have the hash value you pass in as hash — and bestie, that hash has to have been generated beforehand using the CK_HS_HASH(3) macro. Don't be out here making up hashes, the hash set will know. 😭

If the call to ck_hs_fas(3) goes well, then congrats, the key in key is now successfully stored in the hash set pointed to by hs ✨ BUT — important — the key must already exist in the hash set. This is a replace, not an insert, iykyk. The existing entry gets replaced by key, and the previous value gets stored into the void pointer that previous points to. 🎀

If the key does not exist in the hash set, then the function returns false and the hash set is left unchanged — nothing happens, no drama, we move on. 🙈

And the part that's genuinely kind of a slay: this function is guaranteed to be stable with respect to memory usage. It's not out here allocating chaos behind your back. 👑

⭐ RETURN VALUES ⭐

• On a successful completion, ck_hs_fas(3) returns true 🌈
• Otherwise it returns false on failure 💀

💀 ERRORS 💀

Behavior is undefined if key or hs are uninitialized. Not "kinda weird", not "probably fine" — UNDEFINED. Init your stuff first, bestie, I am begging. 😭

👑 SEE ALSO 👑

go read these next, they're the whole friend group:

• ck_hs_init(3)
• 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_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)

There's more lore available at http://concurrencykit.org/ if you wanna go deeper 💜

and that's the whole page, mwah 💅 this one's from the Concurrency Kit fam (that's libck, version dated June 20, 2013), and yes the manual page itself is called CK_HS_FAS(3). go forth and hash responsibly 🫶✨