9p-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)