INTMAP(2)                                               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 pre-
          vious value.  Caninsertkey is like insertkey but 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.

          In anticipation of the storage of reference-counted struc-
          tures, an increment function inc may be specified at map
          creation time.  Lookupkey calls inc (if non-zero) on point-
          ers before returning them.  If the reference count adjust-
          ments were left to the caller (and thus not protected by the
          lock), it would be possible to accidentally reclaim a struc-
          ture if, for example, it was deleted from the map and its
          reference 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

     Page 1                       Plan 9             (printed 7/22/24)

     INTMAP(2)                                               INTMAP(2)

          function transfers responsibility for the reference to the
          map, and responsibility is given back via the return value
          of deletekey or the next insertkey.

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


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

     Page 2                       Plan 9             (printed 7/22/24)