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)