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