GopherProxy

	tventi-cache.3 - plan9port - [fork] Plan 9 from user space
	git clone git://src.adamsgaard.dk/plan9port
	Log
	Files
	Refs
	README
	LICENSE
	---
	tventi-cache.3 (4852B)
	---
	1 .TH VENTI-CACHE 3
	2 .SH NAME
	3 VtBlock, VtCache,
	4 vtblockcopy,
	5 vtblockduplock,
	6 vtblockput,
	7 vtblockwrite,
	8 vtcachealloc,
	9 vtcacheallocblock,
	10 vtcachefree,
	11 vtcacheglobal,
	12 vtcachelocal,
	13 vtcachesetwrite,
	14 vtglobaltolocal,
	15 vtlocaltoglobal \- Venti block cache
	16 .SH SYNOPSIS
	17 .ft L
	18 #include <u.h>
	19 .br
	20 #include <libc.h>
	21 .br
	22 #include <venti.h>
	23 .ta +\w'\fLxxxx 'u
	24 .PP
	25 .ft L
	26 .nf
	27 typedef struct VtBlock
	28 {
	29 uchar *data;
	30 uchar type;
	31 uchar score[VtScoreSize];
	32 u32int addr;
	33 ...
	34 } VtBlock;
	35 .ta +\w'\fLVtBlock* 'u +\w'\fLxxxxxxxx'u
	36 .PP
	37 .B
	38 VtCache* vtcachealloc(VtConn *z, ulong maxmem);
	39 .PP
	40 .B
	41 void vtcachefree(VtCache *c);
	42 .PP
	43 .B
	44 u32int vtglobaltolocal(uchar score[VtScoreSize])
	45 .br
	46 .B
	47 void vtlocaltoglobal(u32int local, uchar score[VtScoreSize])
	48 .PP
	49 .B
	50 VtBlock* vtcacheallocblock(VtCache *c, int type, ulong size);
	51 .PP
	52 .B
	53 VtBlock* vtcachelocal(VtCache *c, u32int addr, int type);
	54 .PP
	55 .B
	56 VtBlock* vtcacheglobal(VtCache *c, uchar[VtScoreSize], int type, …
	57 .PP
	58 .B
	59 void vtblockput(VtBlock *b);
	60 .PP
	61 .B
	62 void vtblockduplock(VtBlock *b);
	63 .PP
	64 .B
	65 int vtblockwrite(VtBlock *b);
	66 .PP
	67 .B
	68 void vtcachesetwrite(VtCache *c,
	69 .br
	70 .B
	71 int (write)(VtConn, uchar[VtScoreSize], uint, uchar*, int));
	72 .PP
	73 .B
	74 VtBlock* vtblockcopy(VtBlock *b);
	75 .SH DESCRIPTION
	76 These functions provide access to a simple in-memory
	77 cache of blocks already stored on a Venti server
	78 and blocks that will eventually be stored on a Venti server.
	79 .PP
	80 A
	81 .B VtBlock
	82 represents a venti data block.
	83 Blocks stored on a venti server,
	84 called
	85 .IR "global blocks" ,
	86 are named by the SHA1 hash of their contents.
	87 This hash is recorded as the block's
	88 .IR score .
	89 Such blocks are immutable.
	90 The cache also stores mutable blocks that have not yet been
	91 written to a venti server. These blocks are called
	92 .IR "local blocks" ,
	93 and have special scores that are 16 zero bytes
	94 followed by a 4-byte big-endian
	95 .IR address .
	96 The address is an index into the internal set of cache blocks.
	97 .PP
	98 The user-visible contents of a
	99 .B VtBlock
	100 are
	101 .BR data ,
	102 a pointer to the data;
	103 .BR type ,
	104 the venti block type;
	105 .BR score ,
	106 the block's score;
	107 and
	108 .BR addr ,
	109 the block's cache address.
	110 .PP
	111 .I Vtcachealloc
	112 allocates a new cache using the client connection
	113 .I z
	114 (see
	115 .MR venti-conn (3)
	116 and
	117 .MR venti-client (3) ),
	118 with
	119 .I maxmem
	120 bytes of memory.
	121 .PP
	122 .I Vtcachefree
	123 frees a cache and all the associated blocks.
	124 .PP
	125 .I Vtglobaltolocal
	126 returns the local address corresponding to the given
	127 local
	128 .IR score .
	129 If passed a global score,
	130 .I vtglobaltolocal
	131 returns the special constant
	132 .B NilBlock
	133 .RB ( ~0 ).
	134 .I Vtlocaltoglobal
	135 is the opposite, setting
	136 .I score
	137 to the local score for the cache address
	138 .IR local .
	139 .PP
	140 .I Vtcacheallocblock
	141 allocates a new local block with the given
	142 .I type
	143 and
	144 .IR size .
	145 .PP
	146 .I Vtcachelocal
	147 retrieves the local block at address
	148 .I addr
	149 from the cache.
	150 The given
	151 .I type
	152 must match the type of the block found at
	153 .IR addr .
	154 .PP
	155 .I Vtcacheglobal
	156 retrieves the block with the given
	157 .IR score ,
	158 .I dtype
	159 and
	160 .I size
	161 from the cache, consulting the Venti server
	162 if necessary.
	163 If passed a local score,
	164 .I vtcacheglobal
	165 invokes
	166 .I vtcachelocal
	167 appropriately.
	168 .PP
	169 The block references returned by
	170 .IR vtcacheallocblock ,
	171 .IR vtcachelocal ,
	172 and
	173 .I vtcacheglobal
	174 must be released when no longer needed.
	175 .I Vtblockput
	176 releases such a reference.
	177 .PP
	178 It is occasionally convenient to have multiple variables
	179 refer to the same block.
	180 .I Vtblockduplock
	181 increments the block's reference count so that
	182 an extra
	183 .I vtblockput
	184 will be required in order to release the block.
	185 .PP
	186 .I Vtblockwrite
	187 writes a local block to the Venti server,
	188 changing the block to a global block.
	189 It calls the cache's
	190 .I write
	191 function
	192 to write the block to the server.
	193 The default
	194 .I write
	195 function is
	196 .I vtwrite
	197 (see
	198 .MR venti-client (3) );
	199 .I vtsetcachewrite
	200 sets it.
	201 .I Vtsetcachewrite
	202 is used by clients to install replacement functions
	203 that run writes in the background or perform other
	204 additional processing.
	205 .PP
	206 .I Vtblockcopy
	207 copies a block in preparation for modifying its contents.
	208 The old block may be a local or global block,
	209 but the new block will be a local block.
	210 .PP
	211 The cache only evicts global blocks.
	212 Local blocks can only leave the cache via
	213 .IR vtblockwrite ,
	214 which turns them into global blocks, making them candidates for
	215 eviction.
	216 .PP
	217 If a new cache block must be allocated (for
	218 .IR vtcacheallocblock ,
	219 .IR vtcachelocal ,
	220 .IR vtcacheglobal ,
	221 or
	222 .IR vtblockcopy ),
	223 but the cache is filled (with local blocks and blocks that
	224 have not yet been released with
	225 .IR vtblockput ),
	226 the library prints the score and reference count of
	227 every block in the cache and then aborts.
	228 A full cache indicates either that the cache is too small,
	229 or, more commonly, that cache blocks are being leaked.
	230 .SH SOURCE
	231 .B \*9/src/libventi
	232 .SH SEE ALSO
	233 .MR venti (3) ,
	234 .MR venti-client (3) ,
	235 .MR venti-conn (3) ,
	236 .MR venti-file (3) ,
	237 .MR venti (7)