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)