t9p-intmap.3 - plan9port - [fork] Plan 9 from user space
 (HTM) git clone git://src.adamsgaard.dk/plan9port
 (DIR) Log
 (DIR) Files
 (DIR) Refs
 (DIR) README
 (DIR) LICENSE
       ---
       t9p-intmap.3 (2625B)
       ---
            1 .TH 9P-INTMAP 3
            2 .SH NAME
            3 Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey,
            4 deletekey \- integer to data structure maps
            5 .SH SYNOPSIS
            6 .ft L
            7 .nf
            8 #include <u.h>
            9 #include <libc.h>
           10 #include <fcall.h>
           11 #include <thread.h>
           12 #include <9p.h>
           13 .fi
           14 .PP
           15 .ft L
           16 .nf
           17 .ta \w'\fLIntmap* 'u
           18 Intmap*        allocmap(void (*inc)(void*))
           19 void        freemap(Intmap *map, void (*dec)(void*))
           20 void*        lookupkey(Intmap *map, ulong key)
           21 void*        insertkey(Intmap *map, ulong key, void *val)
           22 int        caninsertkey(Intmap *map, ulong key, void *val)
           23 void*        lookupkey(Intmap *map, ulong key)
           24 void*        deletekey(Intmap *map, ulong key)
           25 .fi
           26 .SH DESCRIPTION
           27 An
           28 .B Intmap
           29 is an arbitrary mapping from integers to pointers.
           30 .I Allocmap
           31 creates a new map, and
           32 .I freemap
           33 destroys it.
           34 The
           35 .I inc
           36 function is called each time a new pointer is added
           37 to the map; similarly, 
           38 .I dec
           39 is called on each pointer left in the map
           40 when it is being freed.
           41 Typically these functions maintain reference counts.
           42 New entries are added to the map by calling
           43 .IR insertkey ,
           44 which will return the previous value
           45 associated with the given
           46 .IR key ,
           47 or zero if there was no previous value.
           48 .I Caninsertkey
           49 is like
           50 .I insertkey
           51 but only inserts 
           52 .I val
           53 if there is no current mapping.
           54 It returns 1 if
           55 .I val
           56 was inserted, 0 otherwise.
           57 .I Lookupkey
           58 returns the pointer associated with
           59 .IR key ,
           60 or zero if there is no such pointer.
           61 .I Deletekey
           62 removes the entry for 
           63 .I id
           64 from the map, returning the
           65 associated pointer, if any.
           66 .PP
           67 Concurrent access to
           68 .BR Intmap s
           69 is safe, 
           70 moderated via a 
           71 .B QLock 
           72 stored in the 
           73 .B Intmap
           74 structure.
           75 .PP
           76 In anticipation of the storage of reference-counted
           77 structures, an increment function 
           78 .I inc
           79 may be specified
           80 at map creation time.
           81 .I Lookupkey
           82 calls
           83 .I inc 
           84 (if non-zero)
           85 on pointers before returning them.
           86 If the reference count adjustments were
           87 left to the caller (and thus not protected by the lock),
           88 it would be possible to accidentally reclaim a structure
           89 if, for example, it was deleted from the map and its
           90 reference count decremented between the return
           91 of 
           92 .I insertkey
           93 and the external increment.
           94 .IR Insertkey
           95 and
           96 .IR caninsertkey
           97 do
           98 .I not
           99 call
          100 .I inc
          101 when inserting 
          102 .I val
          103 into the map, nor do
          104 .I insertkey
          105 or
          106 .I deletekey
          107 call
          108 .I inc
          109 when returning old map entries.
          110 The rationale is that calling
          111 an insertion function transfers responsibility for the reference
          112 to the map, and responsibility is given back via the return value of
          113 .I deletekey
          114 or the next
          115 .IR insertkey .
          116 .PP
          117 .BR Intmap s
          118 are used by the 9P library to implement
          119 .BR Fidpool s
          120 and
          121 .BR Reqpool s.
          122 .SH SOURCE
          123 .B \*9/src/lib9p/intmap.c
          124 .SH SEE ALSO
          125 .MR 9p (3) ,
          126 .MR 9p-fid (3)