glenda.party
term% ls -F
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)