10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
127 lines
2.6 KiB
Groff
127 lines
2.6 KiB
Groff
.TH 9P-INTMAP 3
|
|
.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 \*9/src/lib9p/intmap.c
|
|
.SH SEE ALSO
|
|
.MR 9p 3 ,
|
|
.MR 9p-fid 3
|