venti-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, ulong size); 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)