o5r/plan9port
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

done

Browse source
This commit is contained in:
rsc 2005-07-18 22:41:58 +00:00
parent 9f95eb6fd6
commit 3aec33fee9
20 changed files with 635 additions and 541 deletions
Download patch file Download diff file Expand all files Collapse all files

66
man/man3/venti-cache.3
View file

@ -24,6 +24,8 @@ vtlocaltoglobal \- Venti block cache
#include <venti.h>
.ta +\w'\fLxxxx 'u
.PP
.ft L
.nf
typedef struct VtBlock
{
uchar *data;
@ -35,16 +37,13 @@ typedef struct VtBlock
.ta +\w'\fLVtBlock* 'u +\w'\fLxxxxxxxx'u
.PP
.B
VtCache* vtcachealloc(VtConn *z, int blocksize, ulong nblocks, int mode);
VtCache* vtcachealloc(VtConn *z, int blocksize, ulong nblocks);
.PP
.B
void vtcachefree(VtCache *c);
.PP
.B
u32int vtcacheblocksize(VtCache *c);
.br
.B
int (*write)(VtConn*, uchar[VtScoreSize], uint, uchar*, int));
.PP
.B
u32int vtglobaltolocal(uchar score[VtScoreSize])
@ -72,6 +71,9 @@ 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);
@ -83,6 +85,37 @@ 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
@ -99,8 +132,22 @@ of maximum block size
frees a cache and all the associated blocks.
.PP
.I Vtcacheblocksize
returns the cache's maximum block size.
.PP
XXX global vs local blocks
.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
@ -124,8 +171,9 @@ from the cache, consulting the Venti server
if necessary.
If passed a local score,
.I vtcacheglobal
behaves as
.IR vtcachelocal .
invokes
.I vtcachelocal
appropriately.
.PP
The block references returned by
.IR vtcacheallocblock ,
@ -191,8 +239,8 @@ or, more commonly, that cache blocks are being leaked.
.SH SOURCE
.B \*9/src/libventi
.SH SEE ALSO
.IR venti (1),
.IR venti (3),
.IR venti-client (3),
.IR venti-conn (3),
.IR venti-file (3)
.IR venti-file (3),
.IR venti (7)

24
man/man3/venti-client.3
View file

@ -8,7 +8,7 @@ vtconnect, vthello, vtread, vtwrite, vtreadpacket, vtwritepacket, vtsync, vtping
#include <libc.h>
.br
#include <venti.h>
.ta +\w'\fLextern int 'u +\w'\fLxxxxxxxx'u
.ta +\w'\fLPacket* 'u +\w'\fLxxxxxxxx'u
.PP
.B
Packet* vtrpc(VtConn *z, Packet *p)
@ -50,7 +50,7 @@ int vtsync(VtConn *z)
int vtping(VtConn *z)
.PP
.B
extern int ventidoublechecksha1; /* default 1 */
extern int ventidoublechecksha1; /* default 1 */
.SH DESCRIPTION
These routines execute the client side of the
.IR venti (7)
@ -73,10 +73,8 @@ is typically called only indirectly, via the functions below.
.I Vthello
executes a
.B hello
transaction
(see
.IR venti (7)), setting
.IB z -> sid
transaction, setting
.IB z ->sid
to the name used by the server.
.I Vthello
is typically called only indirectly, via
@ -103,11 +101,11 @@ reads the block with the given
and
.I type
from the server,
writes the returned data
to
stores the returned data
in memory at
.IR buf ,
and returns the number of bytes retrieved.
If the stored block has size larger than
and returns the number of bytes read.
If the server's block has size larger than
.IR n ,
.I vtread
does not modify
@ -120,7 +118,7 @@ writes the
.I n
bytes in
.I buf
with type
as a block of the given
.IR type ,
setting
.IR score .
@ -177,7 +175,6 @@ as described in
.SH SOURCE
.B \*9/src/libventi
.SH SEE ALSO
.IR venti (1),
.IR venti (3),
.IR venti-conn (3),
.IR venti-packet (3),
@ -190,5 +187,4 @@ return nil on error.
The other routines return \-1 on error.
.PP
.I Vtwrite
returns 0 on success,
meaning it wrote the entire block.
returns 0 on success: there are no partial writes.

16
man/man3/venti-conn.3
View file

@ -61,6 +61,18 @@ A
.B VtConn
structure represents a connection to a Venti server
(when used by a client) or to a client (when used by a server).
It contains the following user-visible fields:
.BR debug ,
a flag enabling debugging prints;
.BR version ,
the protocol version in use;
.BR uid ,
the (unverified) name of the client;
.BR sid ,
the (unverified) name of the server;
and
.BR addr ,
the network address of the remote side.
.PP
.I Vtconn
initializes a new connection structure using file descriptors
@ -81,7 +93,7 @@ exchanges version information with the remote side
as described in
.IR venti (7).
The negotiated version is stored in
.IB z -> version \fR.
.IB z ->version \fR.
.PP
.I Vtsend
writes a packet
@ -146,7 +158,7 @@ must be the connection structure
.I Vtdebug
prints the formatted message to standard error
when
.IB z -> debug
.IB z ->debug
is set. Otherwise it is a no-op.
.PP
.I Vthangup

28
man/man3/venti-fcall.3
View file

@ -14,7 +14,7 @@ vtputstring,
vtrootpack,
vtrootunpack,
vtparsescore,
vtscorefmt \- Venti external data representation
vtscorefmt \- venti data formats
.SH SYNOPSIS
.PP
.ft L
@ -31,7 +31,6 @@ enum
{
VtEntrySize = 40,
VtRootSize = 300,
VtRootVersion = 2,
VtScoreSize = 20,
};
.PP
@ -39,9 +38,9 @@ enum
.nf
typedef struct VtEntry
{
ulong gen; /* generation number */
ushort psize; /* pointer block size */
ushort dsize; /* data block size */
ulong gen; /* generation number */
ushort psize; /* pointer block size */
ushort dsize; /* data block size */
uchar type;
uchar flags;
uvlong size;
@ -54,9 +53,9 @@ typedef struct VtRoot
{
char name[128];
char type[128];
uchar score[VtScoreSize]; /* to a Dir block */
ushort blocksize; /* maximum block size */
uchar prev[VtScoreSize]; /* previous root block */
uchar score[VtScoreSize]; /* to a Dir block */
ushort blocksize; /* maximum block size */
uchar prev[VtScoreSize]; /* previous root block */
} VtRoot;
.ta +\w'\fLPacket* 'u
.PP
@ -110,7 +109,7 @@ converts a
.B VtEntry
structure describing a Venti file
(see
.IR venti (1))
.IR venti (7))
into a 40-byte
.RB ( VtEntrySize )
structure at
@ -150,7 +149,7 @@ frees the strings
.IB f ->uid \fR,
.IB f ->sid \fR,
the buffers
.I f ->crypto
.IB f ->crypto
and
.IB f ->codec \fR,
and the packet
@ -159,11 +158,11 @@ and the packet
The block type enumeration defined in
.B <venti.h>
(presented in
.IR venti (1))
.IR venti (7))
differs from the one used on disk and in the network
protocol.
The disk and network representation uses different
constants does not distinguish between
constants and does not distinguish between
.BI VtDataType+ n
and
.BI VtDirType+ n
@ -173,7 +172,10 @@ converts a
.B <venti.h>
enumeration value to the disk value;
.I vtfromdisktype
converts a disk value to the enumeration value.
converts a disk value to the enumeration value,
always using the
.B VtDataType
pointers.
The
.B VtFcall
field

63
man/man3/venti-file.3
View file

@ -1,29 +1,29 @@
.TH VENTI-FILE 3
.SH NAME
VtFile,
vtfileopenroot,
vtfilecreateroot,
vtfileopen,
vtfilecreate,
vtfileblock,
vtfileread,
vtfilewrite,
vtfileflush,
vtfileincref,
vtfileclose,
vtfilegetentry,
vtfilesetentry,
vtfileblockscore,
vtfileclose,
vtfilecreate,
vtfilecreateroot,
vtfileflush,
vtfileflushbefore,
vtfilegetdirsize,
vtfilesetdirsize,
vtfileunlock,
vtfilegetentry,
vtfilegetsize,
vtfileincref,
vtfilelock,
vtfilelock2,
vtfileflushbefore,
vtfiletruncate,
vtfilegetsize,
vtfileopen,
vtfileopenroot,
vtfileread,
vtfileremove,
vtfilesetdirsize,
vtfilesetentry,
vtfilesetsize,
vtfileremove \- Venti files
vtfiletruncate,
vtfileunlock,
vtfilewrite \- Venti files
.SH SYNOPSIS
.ta +\w'\fLVtBlock* 'u
.PP
@ -85,7 +85,8 @@ int vtfilegetentry(VtFile *f, VtEntry *e);
int vtfilesetentry(VtFile *f, VtEntry *e);
.PP
.B
int vtfileblockscore(VtFile *f, u32int n, uchar score[VtScoreSize]);
int vtfileblockscore(VtFile *f, u32int n,
uchar score[VtScoreSize]);
.PP
.B
int vtfilelock(VtFile *f, int mode);
@ -98,11 +99,11 @@ void vtfileunlock(VtFile *f);
.SH DESCRIPTION
These routines provide a simple interface to create and
manipulate Venti file trees (see
.IR venti (1)).
.IR venti (7)).
.PP
.I Vtfilecreateroot
creates a new Venti file.
.I Btype
.I Type
must be either
.B VtDataType
or
@ -111,7 +112,7 @@ specifying a data or directory file.
.I Dsize
is the block size to use for leaf (data or directory) blocks in the hash tree;
.I psize
is the block size to use for intermediate (pointer) blocks.
is the block size to use for internal (pointer) blocks.
.PP
.I Vtfileopenroot
opens an existing Venti file described by
@ -124,19 +125,19 @@ entry in the directory
.IR f .
.I Mode
should be one of
.IR VtOREAD ,
.IR VtOWRITE ,
.BR VtOREAD ,
.BR VtOWRITE ,
or
.IR VtORDWR ,
.BR VtORDWR ,
indicating how the returned file is to be used.
The
.IR VtOWRITE
.BR VtOWRITE
and
.IR VtORDWR
.BR VtORDWR
modes can only be used if
.IR f
is open with mode
.IR VtORDWR .
.BR VtORDWR .
.PP
.I Vtfilecreate
creates a new file in the directory
@ -239,7 +240,7 @@ Loops that
.I vtfilewrite
should call
.I vtfileflushbefore
regularly to avoid filling the block cache with dirty blocks.
regularly to avoid filling the block cache with unwritten blocks.
.PP
.I Vtfiletruncate
changes the file
@ -283,7 +284,7 @@ to be
returns in
.I score
the score of the
.I n th
.IR n th
block in the file
.IR f .
.PP
@ -318,7 +319,7 @@ in the same directory block.
.SH SOURCE
.B \*9/src/libventi/file.c
.SH SEE ALSO
.IR venti (1),
.IR venti-cache (3),
.IR venti-conn (3),
.IR venti-client (3)
.IR venti-client (3),
.IR venti (7)

15
man/man3/venti-log.3
View file

@ -50,17 +50,19 @@ extern char *VtServerLog; /* "libventi/server" */
These routines provide an in-memory circular log
structure used by the Venti library and the Venti server
to record events for debugging purposes.
The logs have textual names represented as UTF strings.
The logs are named by UTF strings.
.PP
.I Vtlogopen
returns a reference to the log named
returns a reference to the log with the given
.I name .
If a log with that name does not exist and
.I size
is non-zero, a new log capable of holding at
is non-zero,
.I vtlogopen
creates a new log capable of holding at
least
.I size
bytes is allocated and returned.
bytes and returns it.
.I Vtlogclose
releases the reference returned by
.IR vtlogopen .
@ -126,8 +128,9 @@ and
writes debugging information to the log named
.IR VtServerLog ,
which defaults to the string
.LR libventi/server .
.RB ` libventi/server '.
.SH SOURCE
.B \*9/src/libventi
.SH SEE ALSO
.IR venti (3)
.IR venti (3),
.IR venti (8)

3
man/man3/venti-mem.3
View file

@ -39,10 +39,9 @@ On failure, they print an error message and call
They do not return.
.PP
.I Vtbrk
returns a pointer to a new block of at least
returns a pointer to a new, permanently allocated block of at least
.I size
bytes.
The block cannot be freed.
.PP
.IR Vtmalloc ,
.IR vtrealloc ,

135
man/man3/venti-packet.3
View file

@ -1,11 +1,26 @@
.TH VENTI-PACKET 3
.SH NAME
Packet, packetalloc, packetfree, packetforeign, packetdup,
packetsplit, packetconsume, packettrim, packetheader,
packettrailer, packetprefix, packetappend, packetconcat,
packetpeek, packetcopy, packetfragments,
packetsize, packetasize, packetcompact, packetcmp,
packetstats, packetsha1 \- zero-copy network buffers
Packet,
packetalloc,
packetappend,
packetasize,
packetcmp,
packetconcat,
packetconsume,
packetcopy,
packetdup,
packetforeign,
packetfragments,
packetfree,
packetheader,
packetpeek,
packetprefix,
packetsha1,
packetsize,
packetsplit,
packetstats,
packettrailer,
packettrim \- zero-copy network buffers
.SH SYNOPSIS
.ft L
#include <u.h>
@ -21,72 +36,73 @@ packetstats, packetsha1 \- zero-copy network buffers
Packet* packetalloc(void);
.PP
.B
void packetfree(Packet *p)
.PP
.B
Packet* packetforeign(uchar *buf, int n,
.br
.B
void (*free)(void *a), void *a)
.PP
.B
Packet* packetdup(Packet *p, int offset, int n)
.PP
.B
Packet* packetsplit(Packet *p, int n)
.PP
.B
int packetconsume(Packet *p, uchar *buf, int n)
.PP
.B
int packettrim(Packet *p, int offset, int n)
.PP
.B
uchar* packetheader(Packet *p, int n)
.PP
.B
uchar* packettrailer(Packet *p, int n)
.PP
.B
void packetprefix(Packet *p, uchar *buf, int n)
.PP
.B
void packetappend(Packet *p, uchar *buf, int n)
.PP
.B
void packetconcat(Packet *p, Packet *q)
.PP
.B
uchar* packetpeek(Packet *p, uchar *buf, int offset, int n)
.PP
.B
int packetcopy(Packet *p, uchar *buf, int offset, int n)
.PP
.B
int packetfragments(Packet *p, IOchunk *io, int nio,
.br
.B
int offset)
.PP
.B
uint packetsize(Packet *p)
.PP
.B
uint packetasize(Packet *p)
.PP
.B
int packetcmp(Packet *p, Packet *q)
.PP
.B
void packetstats(void)
void packetconcat(Packet *p, Packet *q)
.PP
.B
int packetconsume(Packet *p, uchar *buf, int n)
.PP
.B
int packetcopy(Packet *p, uchar *buf, int offset, int n)
.PP
.B
Packet* packetdup(Packet *p, int offset, int n)
.PP
.B
Packet* packetforeign(uchar *buf, int n,
.br
.B
void (*free)(void *a), void *a)
.PP
.B
int packetfragments(Packet *p, IOchunk *io, int nio,
.br
.B
int offset)
.PP
.B
void packetfree(Packet *p)
.PP
.B
uchar* packetheader(Packet *p, int n)
.PP
.B
uchar* packetpeek(Packet *p, uchar *buf, int offset, int n)
.PP
.B
void packetprefix(Packet *p, uchar *buf, int n)
.PP
.B
void packetsha1(Packet *p, uchar sha1[20])
.PP
.B
uint packetsize(Packet *p)
.PP
.B
Packet* packetsplit(Packet *p, int n)
.PP
.B
void packetstats(void)
.PP
.B
uchar* packettrailer(Packet *p, int n)
.PP
.B
int packettrim(Packet *p, int offset, int n)
.SH DESCRIPTION
A
.B Packet
is a list of blocks of data.
Each block is contiguous in memory, but the entire packet
is a chain of blocks of data.
Each block, called a fragment,
is contiguous in memory, but the entire packet
may not be.
This representation helps avoid unnecessary memory copies.
.PP
@ -107,7 +123,7 @@ returns the number of data bytes allocated to
This may be larger than the number of bytes stored
in
.IR p
because individual fragments may not be filled.
because fragments may not be filled completely.
.PP
.I Packetcmp
compares the data sections of two packets as
@ -214,7 +230,7 @@ computes the SHA1 hash of the data contained in
.IR p .
.PP
.I Packetsize
returns the number of bytes of data contained in
returns the length, in bytes, of the data contained in
.IR p .
.PP
.I Packetsplit
@ -263,4 +279,3 @@ whose return values are described above.
When these functions run out of memory, they
print error messages and call
.IR sysfatal .
They do not return.

7
man/man3/venti-server.3
View file

@ -110,12 +110,13 @@ is a read-only Venti proxy (it rejects
.B write
requests).
.I Devnull
is a write-only Venti server: it discards all
is a dangerous write-only Venti server: it discards all
blocks written to it and returns error on all reads.
.SH SOURCE
.B \*9/src/libventi
.SH SEE ALSO
.IR venti (1),
.IR venti (3),
.IR venti-conn (3),
.IR venti-packet (3)
.IR venti-packet (3),
.IR venti (7),
.IR venti (8)

8
man/man3/venti-zero.3
View file

@ -30,14 +30,14 @@ returns the size of the
buffer pointed to by
.I buf
ignoring trailing zeros or zero scores,
according to the block type
according to the given
.IR type .
.PP
.I Vtzeroextend
pads
.I buf
with zeros or zero scores,
according to the block type
according to the given
.IR type ,
to grow it from
.I size
@ -52,5 +52,5 @@ is the score of the zero-length block.
.br
.B \*9/src/libventi/zeroscore.c
.SH SEE ALSO
.IR venti (1),
.IR venti (3)
.IR venti (3),
.IR venti (7)

10
man/man3/venti.3
View file

@ -1,6 +1,6 @@
.TH VENTI 3
.SH NAME
xxx \- Venti storage server
venti \- archival storage server
.SH SYNOPSIS
.PP
.ft L
@ -28,7 +28,7 @@ describe routines for writing clients
and servers on top of these.
.PP
.IR Venti-fcall (3)
describes the in-memory representation of Venti protocol messages
describes the C representation of Venti protocol messages
and data structures.
It also describes routines that convert between the C representation
and the network and disk representations.
@ -37,7 +37,7 @@ and the network and disk representations.
describes routines for writing clients that manipulate
Venti file trees
(see
.IR venti (1)).
.IR venti (7)).
.PP
.IR Venti-log (3)
describes routines to access in-memory log buffers
@ -51,13 +51,13 @@ routines that abort on error.
.PP
.IR Venti-packet (3)
describes routines for
efficiently manipulating chains of
manipulating zero-copy chains of
data buffers.
.PP
.IR Venti-zero (3)
describes routines to zero truncate and zero extend blocks
(see
.IR venti (1)).
.IR venti (7)).
.SH SOURCE
.B \*9/src/libventi
.SH SEE ALSO