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