harvey/sys/man/2/intmap

.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).