Subversion Repositories planix.SVN

.TH VENTI-CACHE 2

.SH NAME

VtBlock, VtCache, 

vtblockcopy,

vtblockduplock,

vtblockput,

vtblockwrite,

vtcachealloc,

vtcacheallocblock,

vtcacheblocksize,

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, int blocksize, ulong nblocks);

.PP

.B

void	vtcachefree(VtCache *c);

.PP

.B

u32int	vtcacheblocksize(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);

.PP

.B

VtBlock*	vtcachelocal(VtCache *c, u32int addr, int type);

.PP

.B

VtBlock*	vtcacheglobal(VtCache *c, uchar[VtScoreSize], int type);

.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

.IR venti-conn (2)

and

.IR venti-client (2)),

with room for

.I nblocks

of maximum block size

.I blocksize .

.PP

.I Vtcachefree

frees a cache and all the associated blocks.

.PP

.I Vtcacheblocksize

returns the cache's maximum block size.

.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

.IR type .

.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

.I score

and

.I dtype

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

.IR venti-client (2));

.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 /sys/src/libventi

.SH SEE ALSO

.IR venti (2),

.IR venti-client (2),

.IR venti-conn (2),

.IR venti-file (2),

.IR venti (6)