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