libcritnib(3)

💖 libcritnib — an ordered map data structure with lock-free reads 💖

okay bestie, sit DOWN, because this is the critnib manual page and she is lowkey iconic. it's libcritnib, a library for an ordered map data structure, and the whole vibe is that reads are lock-free — readers don't gotta wait on anybody. periodt. 🦋

---

✨ NAME ✨

libcritnib — an ordered map data structure with lock-free reads. that's the whole name, that's the whole assignment, and she ate. 💅

---

🌸 SYNOPSIS 🌸

#include <critnib.h>

and then, like, link her in:

-lcritnib

no cap, that's it. link with -lcritnib and you're in. 🫶

---

👑 DESCRIPTION 👑

🎀 Functions:

okay so here's the whole friend group, one by one, no skips, no cuts. 💜

• critnib *critnib_new(void); — makes you a brand new, empty critnib structure. fresh out the box, zero keys, main character energy. ✨
• void critnib_delete(critnib *c); — destroys her and frees the memory. and listen, important detail: items you removed earlier get reused, but their memory does not get freed until you call this function. so like, the removals were never really gone gone, they were just in the group chat but muted. call this and it's actually over. 😭
• int critnib_insert(critnib *c, uintptr_t key, void *value, int update); — adds a key:value pair to the critnib structure. here's the tea on update: if it's non-zero, a key that already exists gets its value updated (glow up ✨). if it's zero, the function returns EEXIST instead. it may also return ENOMEM if we're out of memory, or 0 if everything went okay. slay.
• void *critnib_remove(critnib *c, uintptr_t key); — yeets a given key out of the structure. you get its associated value back as a parting gift, or 0 (NULL) if there was no such key. sorry bestie, no key, no souvenir. 💀
• void *critnib_get(critnib *c, uintptr_t key); — grabs you a value for a given key, or 0 (NULL) if it's not present. simple, clean, no drama.
• void *critnib_find_le(critnib *c, uintptr_t key); — searches for the largest key not exceeding the argument and hands you its value. like finding the closest thing that didn't overstep. 🧚
• int critnib_find(critnib *c, uintptr_t key, enum find_dir_t dir, uintptr_t *rkey, void **rvalue); — searches for a key that's smaller (FIND_L), smaller-or-equal (FIND_LE), equal (FIND_EQ), greater-or-equal (FIND_GE), or greater (FIND_G) than the argument. if found, the key and value get assigned to *rkey and *rvalue (and yes, those may be null if you wanna skip the assignment, we respect boundaries), and 1 is returned. 💅
• void critnib_iter(critnib *c, uintptr_t min, uintptr_t max, func, void *privdata); — walks the structure, visiting all entries whose keys are at least min but no larger than max (give -1 for no max, live a little). she calls func for every entry she finds. and if func returns a non-zero value, the walk is aborted — that's the emergency exit, bestie. 🚪

the prototype for func should be:

int (*func)(uintptr_t key, void *value, void *privdata);

where privdata is an optional value passed to the iterator.

⚠️ NB. this version of the library implements the iterator in a crude blocking way, stalling any concurrent writers and iterators. it's giving "held the door open for way too long." 😭 this limitation will be lifted in the future, so like, patience is a virtue or whatever. 🕰️

---

that's the whole page, bestie — go forth and map your keys in order, lock-free, no cap. 🌈💖

🌸 this page came to you from the libcritnib manual, rendered by perl v5.38.2, dated 2024-04-22. mwah, kissing you goodbye. 🎀💜