ref: a029cb11d3d19b4064aa0c739707cd4b36742887
dir: /sys/man/2/intmap/
.TH INTMAP 2 .SH NAME Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey, deletekey \- integer to data structure maps .SH SYNOPSIS .ft L .nf #include <u.h> #include <libc.h> #include <fcall.h> #include <thread.h> #include <9p.h> .fi .PP .ft L .nf .ta \w'\fLIntmap* 'u 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) .fi .SH DESCRIPTION An .B Intmap is an arbitrary mapping from integers to pointers. .I Allocmap creates a new map, and .I freemap destroys it. The .I inc function is called each time a new pointer is added to the map; similarly, .I 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 .IR insertkey , which will return the previous value associated with the given .IR key , or zero if there was no previous value. .I Caninsertkey is like .I insertkey but only inserts .I val if there is no current mapping. It returns 1 if .I val was inserted, 0 otherwise. .I Lookupkey returns the pointer associated with .IR key , or zero if there is no such pointer. .I Deletekey removes the entry for .I id from the map, returning the associated pointer, if any. .PP Concurrent access to .BR Intmap s is safe, moderated via a .B QLock stored in the .B Intmap structure. .PP In anticipation of the storage of reference-counted structures, an increment function .I inc may be specified at map creation time. .I Lookupkey calls .I 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 .I insertkey and the external increment. .IR Insertkey and .IR caninsertkey do .I not call .I inc when inserting .I val into the map, nor do .I insertkey or .I deletekey call .I 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 .I deletekey or the next .IR insertkey . .PP .BR Intmap s are used by the 9P library to implement .BR Fidpool s and .BR Reqpool s. .SH SOURCE .B /sys/src/lib9p/intmap.c .SH SEE ALSO .IR 9p (2), .IR 9pfid (2).