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.
238 lines
4.7 KiB
Groff
238 lines
4.7 KiB
Groff
.TH VENTI-CACHE 3
|
|
.SH NAME
|
|
VtBlock, VtCache,
|
|
vtblockcopy,
|
|
vtblockduplock,
|
|
vtblockput,
|
|
vtblockwrite,
|
|
vtcachealloc,
|
|
vtcacheallocblock,
|
|
vtcachefree,
|
|
vtcacheglobal,
|
|
vtcachelocal,
|
|
vtcachesetwrite,
|
|
vtglobaltolocal,
|
|
vtlocaltoglobal \- Venti block cache
|
|
.SH SYNOPSIS
|
|
.ft L
|
|
#include <u.h>
|
|
.br
|
|
#include <libc.h>
|
|
.br
|
|
#include <venti.h>
|
|
.ta +\w'\fLxxxx 'u
|
|
.PP
|
|
.ft L
|
|
.nf
|
|
typedef struct VtBlock
|
|
{
|
|
uchar *data;
|
|
uchar type;
|
|
uchar score[VtScoreSize];
|
|
u32int addr;
|
|
...
|
|
} VtBlock;
|
|
.ta +\w'\fLVtBlock* 'u +\w'\fLxxxxxxxx'u
|
|
.PP
|
|
.B
|
|
VtCache* vtcachealloc(VtConn *z, ulong maxmem);
|
|
.PP
|
|
.B
|
|
void vtcachefree(VtCache *c);
|
|
.PP
|
|
.B
|
|
u32int vtglobaltolocal(uchar score[VtScoreSize])
|
|
.br
|
|
.B
|
|
void vtlocaltoglobal(u32int local, uchar score[VtScoreSize])
|
|
.PP
|
|
.B
|
|
VtBlock* vtcacheallocblock(VtCache *c, int type, ulong size);
|
|
.PP
|
|
.B
|
|
VtBlock* vtcachelocal(VtCache *c, u32int addr, int type);
|
|
.PP
|
|
.B
|
|
VtBlock* vtcacheglobal(VtCache *c, uchar[VtScoreSize], int type, ulong size);
|
|
.PP
|
|
.B
|
|
void vtblockput(VtBlock *b);
|
|
.PP
|
|
.B
|
|
void vtblockduplock(VtBlock *b);
|
|
.PP
|
|
.B
|
|
int vtblockwrite(VtBlock *b);
|
|
.PP
|
|
.B
|
|
void vtcachesetwrite(VtCache *c,
|
|
.br
|
|
.B
|
|
int (*write)(VtConn*, uchar[VtScoreSize], uint, uchar*, int));
|
|
.PP
|
|
.B
|
|
VtBlock* vtblockcopy(VtBlock *b);
|
|
.SH DESCRIPTION
|
|
These functions provide access to a simple in-memory
|
|
cache of blocks already stored on a Venti server
|
|
and blocks that will eventually be stored on a Venti server.
|
|
.PP
|
|
A
|
|
.B VtBlock
|
|
represents a venti data block.
|
|
Blocks stored on a venti server,
|
|
called
|
|
.IR "global blocks" ,
|
|
are named by the SHA1 hash of their contents.
|
|
This hash is recorded as the block's
|
|
.IR score .
|
|
Such blocks are immutable.
|
|
The cache also stores mutable blocks that have not yet been
|
|
written to a venti server. These blocks are called
|
|
.IR "local blocks" ,
|
|
and have special scores that are 16 zero bytes
|
|
followed by a 4-byte big-endian
|
|
.IR address .
|
|
The address is an index into the internal set of cache blocks.
|
|
.PP
|
|
The user-visible contents of a
|
|
.B VtBlock
|
|
are
|
|
.BR data ,
|
|
a pointer to the data;
|
|
.BR type ,
|
|
the venti block type;
|
|
.BR score ,
|
|
the block's score;
|
|
and
|
|
.BR addr ,
|
|
the block's cache address.
|
|
.PP
|
|
.I Vtcachealloc
|
|
allocates a new cache using the client connection
|
|
.I z
|
|
(see
|
|
.MR venti-conn 3
|
|
and
|
|
.MR venti-client 3 ),
|
|
with
|
|
.I maxmem
|
|
bytes of memory.
|
|
.PP
|
|
.I Vtcachefree
|
|
frees a cache and all the associated blocks.
|
|
.PP
|
|
.I Vtglobaltolocal
|
|
returns the local address corresponding to the given
|
|
local
|
|
.IR score .
|
|
If passed a global score,
|
|
.I vtglobaltolocal
|
|
returns the special constant
|
|
.B NilBlock
|
|
.RB ( ~0 ).
|
|
.I Vtlocaltoglobal
|
|
is the opposite, setting
|
|
.I score
|
|
to the local score for the cache address
|
|
.IR local .
|
|
.PP
|
|
.I Vtcacheallocblock
|
|
allocates a new local block with the given
|
|
.I type
|
|
and
|
|
.IR size .
|
|
.PP
|
|
.I Vtcachelocal
|
|
retrieves the local block at address
|
|
.I addr
|
|
from the cache.
|
|
The given
|
|
.I type
|
|
must match the type of the block found at
|
|
.IR addr .
|
|
.PP
|
|
.I Vtcacheglobal
|
|
retrieves the block with the given
|
|
.IR score ,
|
|
.I dtype
|
|
and
|
|
.I size
|
|
from the cache, consulting the Venti server
|
|
if necessary.
|
|
If passed a local score,
|
|
.I vtcacheglobal
|
|
invokes
|
|
.I vtcachelocal
|
|
appropriately.
|
|
.PP
|
|
The block references returned by
|
|
.IR vtcacheallocblock ,
|
|
.IR vtcachelocal ,
|
|
and
|
|
.I vtcacheglobal
|
|
must be released when no longer needed.
|
|
.I Vtblockput
|
|
releases such a reference.
|
|
.PP
|
|
It is occasionally convenient to have multiple variables
|
|
refer to the same block.
|
|
.I Vtblockduplock
|
|
increments the block's reference count so that
|
|
an extra
|
|
.I vtblockput
|
|
will be required in order to release the block.
|
|
.PP
|
|
.I Vtblockwrite
|
|
writes a local block to the Venti server,
|
|
changing the block to a global block.
|
|
It calls the cache's
|
|
.I write
|
|
function
|
|
to write the block to the server.
|
|
The default
|
|
.I write
|
|
function is
|
|
.I vtwrite
|
|
(see
|
|
.MR venti-client 3 );
|
|
.I vtsetcachewrite
|
|
sets it.
|
|
.I Vtsetcachewrite
|
|
is used by clients to install replacement functions
|
|
that run writes in the background or perform other
|
|
additional processing.
|
|
.PP
|
|
.I Vtblockcopy
|
|
copies a block in preparation for modifying its contents.
|
|
The old block may be a local or global block,
|
|
but the new block will be a local block.
|
|
.PP
|
|
The cache only evicts global blocks.
|
|
Local blocks can only leave the cache via
|
|
.IR vtblockwrite ,
|
|
which turns them into global blocks, making them candidates for
|
|
eviction.
|
|
.PP
|
|
If a new cache block must be allocated (for
|
|
.IR vtcacheallocblock ,
|
|
.IR vtcachelocal ,
|
|
.IR vtcacheglobal ,
|
|
or
|
|
.IR vtblockcopy ),
|
|
but the cache is filled (with local blocks and blocks that
|
|
have not yet been released with
|
|
.IR vtblockput ),
|
|
the library prints the score and reference count of
|
|
every block in the cache and then aborts.
|
|
A full cache indicates either that the cache is too small,
|
|
or, more commonly, that cache blocks are being leaked.
|
|
.SH SOURCE
|
|
.B \*9/src/libventi
|
|
.SH SEE ALSO
|
|
.MR venti 3 ,
|
|
.MR venti-client 3 ,
|
|
.MR venti-conn 3 ,
|
|
.MR venti-file 3 ,
|
|
.MR venti 7
|