SCM B-Trees (wb)

6.3 SCM B-Trees

The write-control-bits argument (WCB) to these functions controls the latency of updates to the file after various operations. These bits are defined as follows:

`value`	Name	Meaning
1	WCB-SAP	save block after PUTs
2	WCB-SAR	save block after REMOVEs
4	WCB-SAC	force block save after cached block changes (not currently implemented)
8	WCB-FAC	flush buffer entirely after cached block changes (not currently implemented)

Scheme Procedure: create-bt seg typ wcb ¶: Creates a new root block in seg seg of type typ and returns a bt-handle open to it if successful; otherwise #f. This would typically be used to create a temporary b-tree which should be reclaimed by check if system crashes.

Scheme Procedure: open-bt seg blknum wcb ¶: Returns a bt-handle open to seg number seg, block number blknum if successful; otherwise #f. If no such block exists or is not a root block, #f is returned.

For create-db and open-db, the implicit WCB argument is the combination of ‘WCB-SAP’ and ‘WCB-SAR’.

Scheme Procedure: create-db seg typ name ¶

Returns a B-tree whose name has been entered in the root directory if successful; otherwise #f.

typ should be either

#\D (directory) or
#\T (regular tree).

B-trees with typ #\D which are pointed to by special entries in the root block (1) protect all their special entries from garbage collection by the check program. #\T is for regular (data) arrays.

Scheme Procedure: open-db seg name ¶: Returns the B-tree whose name has been entered in the root directory or #f if not found.

Dirty block buffers can also be flushed to disk by calls to flush-ents. flush-ents can be called at any time after WB is initialized, even by an asynchronous background process.

Scheme Procedure: flush-ents attempts k ¶: k is the number of dirty block buffers to write to disk; attempts is the number of times to try. Note that blocks in any segment may be written by flush-ents. flush-ents returns the number of blocks written.

Block numbers are stored in the directory as four-byte integers. In order to make WB files portable between big-endian and little-endian computers, all conversions of four-byte pointers should be done by str2long and long2str!.

Scheme Procedure: str2long string index ¶: Converts the 4 bytes in string starting at index into an unsigned integer and returns it.

Scheme Procedure: long2str! string index integer ¶: Stores integer into 4 bytes of string starting at index.