term% ls -F
term% cat index.txt
INTMAP(2)                     System Calls Manual                    INTMAP(2)

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

       #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)

       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
       associated 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
       increment  function inc may be specified at map creation time.  Lookup‐
       key calls inc (if non-zero) on pointers before returning them.  If  the
       reference  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

       Intmaps are used by the 9P library to implement Fidpools and Reqpools.


       9p(2), 9pfid(2).