127 lines
2.6 KiB
Plaintext
127 lines
2.6 KiB
Plaintext
|
.TH INTMAP 2
|
||
|
|
.SH NAME
|
||
|
|
Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey,
|
||
|
|
deletekey \- integer to data structure maps
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.ft L
|
||
|
|
.nf
|
||
|
|
#include <u.h>
|
||
|
|
#include <libc.h>
|
||
|
|
#include <fcall.h>
|
||
|
|
#include <thread.h>
|
||
|
|
#include <9p.h>
|
||
|
|
.fi
|
||
|
|
.PP
|
||
|
|
.ft L
|
||
|
|
.nf
|
||
|
|
.ta \w'\fLIntmap* 'u
|
||
|
|
Intmap* allocmap(void (*inc)(void*))
|
||
|
|
void freemap(Intmap *map, void (*dec)(void*))
|
||
|
|
void* lookupkey(Intmap *map, ulong key)
|
||
|
|
void* insertkey(Intmap *map, ulong key, void *val)
|
||
|
|
int caninsertkey(Intmap *map, ulong key, void *val)
|
||
|
|
void* lookupkey(Intmap *map, ulong key)
|
||
|
|
void* deletekey(Intmap *map, ulong key)
|
||
|
|
.fi
|
||
|
|
.SH DESCRIPTION
|
||
|
|
An
|
||
|
|
.B Intmap
|
||
|
|
is an arbitrary mapping from integers to pointers.
|
||
|
|
.I Allocmap
|
||
|
|
creates a new map, and
|
||
|
|
.I freemap
|
||
|
|
destroys it.
|
||
|
|
The
|
||
|
|
.I inc
|
||
|
|
function is called each time a new pointer is added
|
||
|
|
to the map; similarly,
|
||
|
|
.I dec
|
||
|
|
is called on each pointer left in the map
|
||
|
|
when it is being freed.
|
||
|
|
Typically these functions maintain reference counts.
|
||
|
|
New entries are added to the map by calling
|
||
|
|
.IR insertkey ,
|
||
|
|
which will return the previous value
|
||
|
|
associated with the given
|
||
|
|
.IR key ,
|
||
|
|
or zero if there was no previous value.
|
||
|
|
.I Caninsertkey
|
||
|
|
is like
|
||
|
|
.I insertkey
|
||
|
|
but only inserts
|
||
|
|
.I val
|
||
|
|
if there is no current mapping.
|
||
|
|
It returns 1 if
|
||
|
|
.I val
|
||
|
|
was inserted, 0 otherwise.
|
||
|
|
.I Lookupkey
|
||
|
|
returns the pointer associated with
|
||
|
|
.IR key ,
|
||
|
|
or zero if there is no such pointer.
|
||
|
|
.I Deletekey
|
||
|
|
removes the entry for
|
||
|
|
.I id
|
||
|
|
from the map, returning the
|
||
|
|
associated pointer, if any.
|
||
|
|
.PP
|
||
|
|
Concurrent access to
|
||
|
|
.BR Intmap s
|
||
|
|
is safe,
|
||
|
|
moderated via a
|
||
|
|
.B QLock
|
||
|
|
stored in the
|
||
|
|
.B Intmap
|
||
|
|
structure.
|
||
|
|
.PP
|
||
|
|
In anticipation of the storage of reference-counted
|
||
|
|
structures, an increment function
|
||
|
|
.I inc
|
||
|
|
may be specified
|
||
|
|
at map creation time.
|
||
|
|
.I Lookupkey
|
||
|
|
calls
|
||
|
|
.I inc
|
||
|
|
(if non-zero)
|
||
|
|
on pointers before returning them.
|
||
|
|
If the reference count adjustments were
|
||
|
|
left to the caller (and thus not protected by the lock),
|
||
|
|
it would be possible to accidentally reclaim a structure
|
||
|
|
if, for example, it was deleted from the map and its
|
||
|
|
reference count decremented between the return
|
||
|
|
of
|
||
|
|
.I insertkey
|
||
|
|
and the external increment.
|
||
|
|
.IR Insertkey
|
||
|
|
and
|
||
|
|
.IR caninsertkey
|
||
|
|
do
|
||
|
|
.I not
|
||
|
|
call
|
||
|
|
.I inc
|
||
|
|
when inserting
|
||
|
|
.I val
|
||
|
|
into the map, nor do
|
||
|
|
.I insertkey
|
||
|
|
or
|
||
|
|
.I deletekey
|
||
|
|
call
|
||
|
|
.I inc
|
||
|
|
when returning old map entries.
|
||
|
|
The rationale is that calling
|
||
|
|
an insertion function transfers responsibility for the reference
|
||
|
|
to the map, and responsibility is given back via the return value of
|
||
|
|
.I deletekey
|
||
|
|
or the next
|
||
|
|
.IR insertkey .
|
||
|
|
.PP
|
||
|
|
.BR Intmap s
|
||
|
|
are used by the 9P library to implement
|
||
|
|
.BR Fidpool s
|
||
|
|
and
|
||
|
|
.BR Reqpool s.
|
||
|
|
.SH SOURCE
|
||
|
|
.B /sys/src/lib9p/intmap.c
|
||
|
|
.SH SEE ALSO
|
||
|
|
.IR 9p (2),
|
||
|
|
.IR 9pfid (2).
|