Subversion Repositories planix.SVN

Rev

Rev 2 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 - 1 
.TH INTMAP 2
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 /sys/src/lib9p/intmap.c
124 
.SH SEE ALSO
125 
.IR 9p (2),
126 
.IR 9pfid (2).