term% cat index.txt INTMAP(2) System Calls Manual INTMAP(2)
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 an arbitrary mapping from integers to pointers. Allocmap
creates a new map, and freemap destroys it. The inc function is called
each time a new pointer is added to the map; similarly, dec is called
on each pointer left in the map when it is being freed. Typically
these functions maintain reference counts. New entries are added to
the map by calling insertkey, which will return the previous value as‐
sociated with the given key, or zero if there was no previous value.
Caninsertkey is like insertkey but only inserts val if there is no cur‐
rent mapping. It returns 1 if val was inserted, 0 otherwise. Lookup‐
key returns the pointer associated with key, or zero if there is no
such pointer. Deletekey removes the entry for id from the map, return‐
ing the associated pointer, if any.
Concurrent access to Intmaps is safe, moderated via a QLock stored in
the Intmap structure.
In anticipation of the storage of reference-counted structures, an in‐
crement function inc may be specified at map creation time. Lookupkey
calls inc (if non-zero) on pointers before returning them. If the ref‐
erence count adjustments were left to the caller (and thus not pro‐
tected by the lock), it would be possible to accidentally reclaim a
structure if, for example, it was deleted from the map and its refer‐
ence count decremented between the return of insertkey and the external
increment. 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 responsibil‐
ity is given back via the return value of deletekey or the next in‐
sertkey.
Intmaps are used by the 9P library to implement Fidpools and Reqpools.
SOURCE
/sys/src/lib9p/intmap.c
SEE ALSO
9p(2), 9pfid(2).
INTMAP(2)