BTreeVM.mesa
Copyright Ó 1985, 1986, 1988 by Xerox Corporation. All rights reserved.
Created by M. D. Schroeder
Taft, June 9, 1983 2:10 pm
Schroeder, August 18, 1983 11:52 am
Russ Atkinson (RRA) April 22, 1988 7:36:16 pm PDT
Doug Wyatt, February 27, 1985 10:18:19 am PST
Interface for the VM to support the BTree package.
DIRECTORY
BTree USING [ PageNumber, PageSize, ReferencePage, ReleasePage ],
IO USING [ STREAM ];
BTreeVM: CEDAR DEFINITIONS = BEGIN
CacheSize: TYPE = [8..4000]; -- in BTree pages --
Handle: TYPE = REF VMObject;
VMObject: TYPE;
Open:
PROC [ backing:
IO.
STREAM, pageSize: BTree.PageSize, cacheSize: CacheSize,
offset:
CARD ← 0 ]
RETURNS [ Handle ];
The Handle returned should be passed to BTree.Open as the "storage" argument. If you want the BTree on the disk to be maintained in a consistent state, then the BTree should be opened with "maintainRecomputableState" set TRUE. If you don't want this, then you probably should be using another package. "offset" specifies which byte offset is the origin for BTree page zero.
The BTreeVM package has a finialization procedure that will return any virtual memory allocated to the cache whenever all references to the "handle" from outside the package disappear. The client is responsible for the integrity of the cache accross a checkpoint/rollback. The procedures Flush and FreeBuffers below may help in this regard.
ReferencePage: BTree.ReferencePage;
Used by the BTree package to read pages of the BTree file. BTreeVM will automatically extend the backing file as the BTree grows. It never shrinks the backing file, and make no effort to keep the byte count and created-date correct.
ReleasePage: BTree.ReleasePage;
Used by the BTree package to write pages of the BTree file.
GetStats:
PROC [ h: Handle, stats:
REF Stats ];
Stats:
TYPE =
RECORD [
hits, misses, reads, writes, cumChainLength: CARD,
cumReadWriteTime: CARD
];
Returns performance statistics (by assigning to stats^), measured from the time the handle was created. Hits and misses are the number of ReferencePage operations for pages that were and were not already in the cache. Reads and writes are the number of actual reads and writes to the backing file; and cumReadWriteTime is the total amount of time spent waiting for reads and writes. cumChainLength is the total number of hash chain entries searched during all lookups; the average search length is cumChainLength/(hits+misses).
FlushCache:
PROC [ h: Handle ];
Forces out any dirty pages and then renders the cache empty, so that subsequent references will require pages to be read afresh from the file.
FreeBuffers:
PROC [ h: Handle ];
All VM buffers associated with the Handle are freed. The cache is not flushed first.
END.