.TH VENTI-CACHE 2.SH NAMEVtBlock, 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.nftypedef struct VtBlock{	uchar *data;	uchar type;	uchar score[VtScoreSize];	u32int addr;	...} VtBlock;.ta +\w'\fLVtBlock* 'u +\w'\fLxxxxxxxx'u.PP.BVtCache*	vtcachealloc(VtConn *z, int blocksize, ulong nblocks);.PP.Bvoid	vtcachefree(VtCache *c);.PP.Bu32int	vtcacheblocksize(VtCache *c);.PP.Bu32int	vtglobaltolocal(uchar score[VtScoreSize]).br.Bvoid	vtlocaltoglobal(u32int local, uchar score[VtScoreSize]).PP.BVtBlock*	vtcacheallocblock(VtCache *c, int type);.PP.BVtBlock*	vtcachelocal(VtCache *c, u32int addr, int type);.PP.BVtBlock*	vtcacheglobal(VtCache *c, uchar[VtScoreSize], int type);.PP.Bvoid	vtblockput(VtBlock *b);.PP.Bvoid	vtblockduplock(VtBlock *b);.PP.Bint	vtblockwrite(VtBlock *b);.PP.Bvoid	vtcachesetwrite(VtCache *c,.br.B	   int (*write)(VtConn*, uchar[VtScoreSize], uint, uchar*, int));.PP.BVtBlock*	vtblockcopy(VtBlock *b);.SH DESCRIPTIONThese functions provide access to a simple in-memorycache of blocks already stored on a Venti serverand blocks that will eventually be stored on a Venti server..PPA .B VtBlockrepresents 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 beenwritten to a venti server.  These blocks are called.IR "local blocks" ,and have special scores that are 16 zero bytesfollowed by a 4-byte big-endian.IR address .The address is an index into the internal set of cache blocks..PPThe user-visible contents of a.B VtBlockare.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 Vtcacheallocallocates a new cache using the client connection.I z(see.IR venti-conn (2)and.IR venti-client (2)),with room for.I nblocksof maximum block size.I blocksize ..PP.I Vtcachefreefrees a cache and all the associated blocks..PP.I Vtcacheblocksizereturns the cache's maximum block size..PP.I Vtglobaltolocalreturns the local address corresponding to the givenlocal.IR score .If passed a global score,.I vtglobaltolocalreturns the special constant.B NilBlock.RB ( ~0 )..I Vtlocaltoglobalis the opposite, setting.I scoreto the local score for the cache address.IR local ..PP.I Vtcacheallocblockallocates a new local block with the given.IR type ..PP.I Vtcachelocalretrieves the local block at address.I addrfrom the cache.The given.I typemust match the type of the block found at.IR addr ..PP.I Vtcacheglobalretrieves the block with the given.I scoreand.I dtypefrom the cache, consulting the Venti serverif necessary.If passed a local score,.I vtcacheglobalinvokes.I vtcachelocalappropriately..PPThe block references returned by.IR vtcacheallocblock ,.IR vtcachelocal ,and.I vtcacheglobalmust be released when no longer needed..I Vtblockputreleases such a reference..PPIt is occasionally convenient to have multiple variablesrefer to the same block..I Vtblockduplockincrements the block's reference count so thatan extra .I vtblockputwill be required in order to release the block..PP.I Vtblockwritewrites a local block to the Venti server,changing the block to a global block.It calls the cache's.I writefunctionto write the block to the server.The default.I writefunction is .I vtwrite(see.IR venti-client (2));.I vtsetcachewritesets it..I Vtsetcachewriteis used by clients to install replacement functions that run writes in the background or perform otheradditional processing..PP.I Vtblockcopycopies 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..PPThe cache only evicts global blocks.Local blocks can only leave the cache via.IR vtblockwrite ,which turns them into global blocks, making them candidates foreviction..PPIf 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 thathave not yet been released with.IR vtblockput ),the library prints the score and reference count ofevery 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)