.TH DISKBLOCKS 2.SH NAMEDiskblocks: Block, Disk, tempfile \- temporary storage of variable-sized blocks.SH SYNOPSIS.EXinclude "diskblocks.m";diskblocks := load Diskblocks Diskblocks->PATH;Block: adt { addr: big; # address on file n: int; # size in bytes};Disk: adt { init: fn(fd: ref Sys->FD, gran: int, maxblock: int): ref Disk; new: fn(d: self ref Disk, n: int): ref Block; release: fn(d: self ref Disk, b: ref Block); read: fn(d: self ref Disk, b: ref Block, a: array of byte, n: int): int; write: fn(d: self ref Disk, b: ref Block, a: array of byte, n: int): ref Block;};init: fn();tempfile: fn(): ref Sys->FD;.EE.SH DESCRIPTION.B Diskblocksmanages a set of variable-sized blocks on a temporary file..PP.B Initmust be called before any other function in the module..PPEach block has an address and a size in bytes, represented by a value of type.BR Block ..PPEach file is represented by the type.BR Disk ,providing the following operations:.TF 8n.TP.BI init( fd\f5,\fP\ gran\f5,\fP\ maxblock )Initialises the file.I fdfor use as temporary block storage and returns a reference to a.B Diskto describe it..I Fdmust be open for reading and writing, and must refer to a file that allows random access.Blocks are allocated in multiples of the granularity.IR gran ,in bytes;the largest possible block is.I maxblockbytes, which must be a multiple of.IR gran ..TP.IB d .new( n )Allocate a block of.I nbytes on Disk.I dand return a reference to it..TP.IB d .release( b )Free the Block.IR b ,making it available for reallocation..TP.IB d .write( b\f5,\fP\ a\f5,\fP\ n )Write.I nbytes from array.I ato Block.I bon Disk.IR d ,returning a reference to the resulting Block.If.I bis nil or.I nexceeds.IR b 'scurrent size,.B writeallocates a new block (releasing.IR b ).Thus the returned value might differ from.IR b ,and must be used in subsequent IO requests..TP.IB d .read( b\f5,\fP\ a\f5,\fP\ n )Read.I nbytes from Block.I bon Disk.I dinto array.IR a ,returning the number of bytes read..I Nmust not exceed.IB b .n ..PD.PP.B Tempfilereturns a file descriptor referring to a newly-created temporary file,suitable for use by.BR Disk.init .The file will be removed automaticallywhen the file descriptor is closed..SH SOURCE.B /appl/lib/diskblocks.b.SH DIAGNOSTICSA function that returns an integer returns -1 on error; a function that returns a referencereturns nil on error.The system error string is set in either case.
.TH DISKBLOCKS 2
.SH NAME
Diskblocks: Block, Disk, tempfile \- temporary storage of variable-sized blocks
.SH SYNOPSIS
.EX
include "diskblocks.m";
diskblocks := load Diskblocks Diskblocks->PATH;
Block: adt {
addr: big; # address on file
n: int; # size in bytes
};
Disk: adt {
init: fn(fd: ref Sys->FD, gran: int, maxblock: int): ref Disk;
new: fn(d: self ref Disk, n: int): ref Block;
release: fn(d: self ref Disk, b: ref Block);
read: fn(d: self ref Disk, b: ref Block,
a: array of byte, n: int): int;
write: fn(d: self ref Disk, b: ref Block,
a: array of byte, n: int): ref Block;
};
init: fn();
tempfile: fn(): ref Sys->FD;
.EE
.SH DESCRIPTION
.B Diskblocks
manages a set of variable-sized blocks on a temporary file.
.PP
.B Init
must be called before any other function in the module.
.PP
Each block has an address and a size in bytes, represented by a value of type
.BR Block .
.PP
Each file is represented by the type
.BR Disk ,
providing the following operations:
.TF 8n
.TP
.BI init( fd\f5,\fP\ gran\f5,\fP\ maxblock )
Initialises the file
.I fd
for use as temporary block storage and returns a reference to a
.B Disk
to describe it.
.I Fd
must be open for reading and writing, and must refer to a file that allows random access.
Blocks are allocated in multiples of the granularity
.IR gran ,
in bytes;
the largest possible block is
.I maxblock
bytes, which must be a multiple of
.IR gran .
.TP
.IB d .new( n )
Allocate a block of
.I n
bytes on Disk
.I d
and return a reference to it.
.TP
.IB d .release( b )
Free the Block
.IR b ,
making it available for reallocation.
.TP
.IB d .write( b\f5,\fP\ a\f5,\fP\ n )
Write
.I n
bytes from array
.I a
to Block
.I b
on Disk
.IR d ,
returning a reference to the resulting Block.
If
.I b
is nil or
.I n
exceeds
.IR b 's
current size,
.B write
allocates a new block (releasing
.IR b ).
Thus the returned value might differ from
.IR b ,
and must be used in subsequent IO requests.
.TP
.IB d .read( b\f5,\fP\ a\f5,\fP\ n )
Read
.I n
bytes from Block
.I b
on Disk
.I d
into array
.IR a ,
returning the number of bytes read.
.I N
must not exceed
.IB b .n .
.PD
.PP
.B Tempfile
returns a file descriptor referring to a newly-created temporary file,
suitable for use by
.BR Disk.init .
The file will be removed automatically
when the file descriptor is closed.
.SH SOURCE
.B /appl/lib/diskblocks.b
.SH DIAGNOSTICS
A function that returns an integer returns -1 on error; a function that returns a reference
returns nil on error.
The system error string is set in either case.