9P-INTMAP(3)

okay bestie, this is 9P-INTMAP(3) from the Library Functions Manual 📚💖 — the integer-to-pointer map page, and it's lowkey a whole reference-counting vibe.

🎀 NAME 🎀

Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey, deletekey — integer to data structure maps 🦋

✨ SYNOPSIS ✨

#include <u.h>
#include <libc.h>
#include <fcall.h>
#include <thread.h>
#include <9p.h>

Intmap* allocmap(void (*inc)(void*))
void    freemap(Intmap *map, void (*dec)(void*))
void*   lookupkey(Intmap *map, ulong key)
void*   insertkey(Intmap *map, ulong key, void *val)
int     caninsertkey(Intmap *map, ulong key, void *val)
void*   lookupkey(Intmap *map, ulong key)
void*   deletekey(Intmap *map, ulong key)

🌸 DESCRIPTION 🌸

An Intmap is literally an arbitrary mapping from integers to pointers. No cap, that's the whole concept. Here's the function-by-function tea:

• allocmap — creates a new map. The inc function is called each time a new pointer is added to the map; typically inc maintains reference counts. ✨
• freemap — destroys the map. The dec function is called on each pointer left in the map when it is being freed; typically dec maintains reference counts. 🫶
• insertkey — adds new entries to the map. It returns the previous value associated with the given key, or zero if there was no previous value.
• caninsertkey — like insertkey, but it only inserts val if there is no current mapping. It returns 1 if val was inserted, 0 otherwise. 💅
• lookupkey — returns the pointer associated with key, or zero if there is no such pointer.
• deletekey — removes the entry for id from the map, returning the associated pointer, if any.

Concurrent access to Intmaps is safe, moderated via a QLock stored in the Intmap structure. Thread-safe icon behavior, fr fr. 🔥

In anticipation of the storage of reference-counted structures, an increment function inc may be specified at map creation time. lookupkey calls inc (if non-zero) on pointers before returning them. If the reference count adjustments were left to the caller (and thus not protected by the lock), it would be possible to accidentally reclaim a structure if, for example, it was deleted from the map and its reference count decremented between the return of insertkey and the external increment. So the lock is doing important main character work, okay? 😭

insertkey and caninsertkey do not call inc when inserting val into the map, nor do insertkey or deletekey call inc when returning old map entries. The rationale is that calling an insertion function transfers responsibility for the reference to the map, and responsibility is given back via the return value of deletekey or the next insertkey. Periodt. 💅

Intmaps are used by the 9P library to implement Fidpools and Reqpools. Iconic crossover event. 🫶

📁 SOURCE 📁

/src/lib9p/intmap.c

🔗 SEE ALSO 🔗

9p(3), 9p-fid(3)

that's the whole 9P-INTMAP(3) situation, bestie — Library Functions Manual page, source at /src/lib9p/intmap.c, and the footer is just the page name with no extra date drama. byeee 💖