1 cfa37a7b 2004-04-10 devnull .TH INTMAP 3
3 cfa37a7b 2004-04-10 devnull Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey,
4 cfa37a7b 2004-04-10 devnull deletekey \- integer to data structure maps
5 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
8 cfa37a7b 2004-04-10 devnull #include <u.h>
9 cfa37a7b 2004-04-10 devnull #include <libc.h>
10 cfa37a7b 2004-04-10 devnull #include <fcall.h>
11 cfa37a7b 2004-04-10 devnull #include <thread.h>
12 cfa37a7b 2004-04-10 devnull #include <9p.h>
17 cfa37a7b 2004-04-10 devnull .ta \w'\fLIntmap* 'u
18 cfa37a7b 2004-04-10 devnull Intmap* allocmap(void (*inc)(void*))
19 cfa37a7b 2004-04-10 devnull void freemap(Intmap *map, void (*dec)(void*))
20 cfa37a7b 2004-04-10 devnull void* lookupkey(Intmap *map, ulong key)
21 cfa37a7b 2004-04-10 devnull void* insertkey(Intmap *map, ulong key, void *val)
22 cfa37a7b 2004-04-10 devnull int caninsertkey(Intmap *map, ulong key, void *val)
23 cfa37a7b 2004-04-10 devnull void* lookupkey(Intmap *map, ulong key)
24 cfa37a7b 2004-04-10 devnull void* deletekey(Intmap *map, ulong key)
26 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
28 cfa37a7b 2004-04-10 devnull .B Intmap
29 cfa37a7b 2004-04-10 devnull is an arbitrary mapping from integers to pointers.
30 cfa37a7b 2004-04-10 devnull .I Allocmap
31 cfa37a7b 2004-04-10 devnull creates a new map, and
32 cfa37a7b 2004-04-10 devnull .I freemap
33 cfa37a7b 2004-04-10 devnull destroys it.
36 cfa37a7b 2004-04-10 devnull function is called each time a new pointer is added
37 cfa37a7b 2004-04-10 devnull to the map; similarly,
39 cfa37a7b 2004-04-10 devnull is called on each pointer left in the map
40 cfa37a7b 2004-04-10 devnull when it is being freed.
41 cfa37a7b 2004-04-10 devnull Typically these functions maintain reference counts.
42 cfa37a7b 2004-04-10 devnull New entries are added to the map by calling
43 cfa37a7b 2004-04-10 devnull .IR insertkey ,
44 cfa37a7b 2004-04-10 devnull which will return the previous value
45 cfa37a7b 2004-04-10 devnull associated with the given
46 cfa37a7b 2004-04-10 devnull .IR key ,
47 cfa37a7b 2004-04-10 devnull or zero if there was no previous value.
48 cfa37a7b 2004-04-10 devnull .I Caninsertkey
50 cfa37a7b 2004-04-10 devnull .I insertkey
51 cfa37a7b 2004-04-10 devnull but only inserts
53 cfa37a7b 2004-04-10 devnull if there is no current mapping.
54 cfa37a7b 2004-04-10 devnull It returns 1 if
56 cfa37a7b 2004-04-10 devnull was inserted, 0 otherwise.
57 cfa37a7b 2004-04-10 devnull .I Lookupkey
58 cfa37a7b 2004-04-10 devnull returns the pointer associated with
59 cfa37a7b 2004-04-10 devnull .IR key ,
60 cfa37a7b 2004-04-10 devnull or zero if there is no such pointer.
61 cfa37a7b 2004-04-10 devnull .I Deletekey
62 cfa37a7b 2004-04-10 devnull removes the entry for
64 cfa37a7b 2004-04-10 devnull from the map, returning the
65 cfa37a7b 2004-04-10 devnull associated pointer, if any.
67 cfa37a7b 2004-04-10 devnull Concurrent access to
68 cfa37a7b 2004-04-10 devnull .BR Intmap s
70 cfa37a7b 2004-04-10 devnull moderated via a
72 cfa37a7b 2004-04-10 devnull stored in the
73 cfa37a7b 2004-04-10 devnull .B Intmap
74 cfa37a7b 2004-04-10 devnull structure.
76 cfa37a7b 2004-04-10 devnull In anticipation of the storage of reference-counted
77 cfa37a7b 2004-04-10 devnull structures, an increment function
79 cfa37a7b 2004-04-10 devnull may be specified
80 cfa37a7b 2004-04-10 devnull at map creation time.
81 cfa37a7b 2004-04-10 devnull .I Lookupkey
84 cfa37a7b 2004-04-10 devnull (if non-zero)
85 cfa37a7b 2004-04-10 devnull on pointers before returning them.
86 cfa37a7b 2004-04-10 devnull If the reference count adjustments were
87 cfa37a7b 2004-04-10 devnull left to the caller (and thus not protected by the lock),
88 cfa37a7b 2004-04-10 devnull it would be possible to accidentally reclaim a structure
89 cfa37a7b 2004-04-10 devnull if, for example, it was deleted from the map and its
90 cfa37a7b 2004-04-10 devnull reference count decremented between the return
92 cfa37a7b 2004-04-10 devnull .I insertkey
93 cfa37a7b 2004-04-10 devnull and the external increment.
94 cfa37a7b 2004-04-10 devnull .IR Insertkey
96 cfa37a7b 2004-04-10 devnull .IR caninsertkey
101 cfa37a7b 2004-04-10 devnull when inserting
103 cfa37a7b 2004-04-10 devnull into the map, nor do
104 cfa37a7b 2004-04-10 devnull .I insertkey
106 cfa37a7b 2004-04-10 devnull .I deletekey
109 cfa37a7b 2004-04-10 devnull when returning old map entries.
110 cfa37a7b 2004-04-10 devnull The rationale is that calling
111 cfa37a7b 2004-04-10 devnull an insertion function transfers responsibility for the reference
112 cfa37a7b 2004-04-10 devnull to the map, and responsibility is given back via the return value of
113 cfa37a7b 2004-04-10 devnull .I deletekey
114 cfa37a7b 2004-04-10 devnull or the next
115 cfa37a7b 2004-04-10 devnull .IR insertkey .
117 cfa37a7b 2004-04-10 devnull .BR Intmap s
118 cfa37a7b 2004-04-10 devnull are used by the 9P library to implement
119 cfa37a7b 2004-04-10 devnull .BR Fidpool s
121 cfa37a7b 2004-04-10 devnull .BR Reqpool s.
122 cfa37a7b 2004-04-10 devnull .SH SOURCE
123 b5fdffee 2004-04-19 devnull .B /usr/local/plan9/src/lib9p/intmap.c
124 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
125 bf8a59fa 2004-04-11 devnull .IR 9p (3),
126 bf8a59fa 2004-04-11 devnull .IR 9pfid (3).
