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