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