|
NAME
| |
Intmap, allocmap, freemap, insertkey, caninsertkey, lookupkey,
deletekey – integer to data structure maps
|
SYNOPSIS
| |
#include <u.h>
#include <libc.h>
#include <fcall.h>
#include <thread.h>
#include <9p.h>
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)
|
DESCRIPTION
| |
An Intmap is an arbitrary mapping from integers to pointers. Allocmap
creates a new map, and freemap destroys it. The inc function is
called each time a new pointer is added to the map; similarly,
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 insertkey, which will return the previous value associated
with the given key, or zero if there was no previous value. Caninsertkey
is like insertkey but only inserts val if there is no current
mapping. It returns 1 if val was inserted, 0 otherwise. Lookupkey
returns the pointer associated with key, or zero if there is no
such pointer. Deletekey
removes the entry for id from the map, returning the associated
pointer, if any.
Concurrent access to Intmaps is safe, moderated via a QLock stored
in the Intmap structure.
In anticipation of the storage of reference-counted structures,
an increment function inc may be specified at map creation time.
Lookupkey calls 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 insertkey and the external increment. Insertkey
and caninsertkey do not call inc when inserting val into the map,
nor do insertkey or deletekey call 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 deletekey or the next insertkey.
Intmaps are used by the 9P library to implement Fidpools and Reqpools.
|
SOURCE
SEE ALSO
|
|
