|  | 
 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 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 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 structures,
    an increment function inc may be specified at map creation time.
    Lookupkey calls 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 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 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 Reqpools. 
 | 
 SOURCE     
 SEE ALSO    
 |  |