-- File DBSegment.mesa
-- Last edited by
-- MBrown on December 16, 1982 2:37 pm
-- Willie-Sue on February 3, 1983 10:38 am
-- Cattell, July 15, 1983 2:48 pm
DIRECTORY
DBCommon,
DBCache USING [CacheHandle],
DBStorageTID USING [TID],
Rope USING [ROPE];
DBSegment: DEFINITIONS = BEGIN
ROPE: TYPE = Rope.ROPE;
Trans: TYPE = DBCommon.Trans;
Segment: TYPE = DBCommon.Segment;
SegmentID: TYPE = DBCommon.SegmentID;
SegmentIndex: TYPE = DBCommon.SegmentIndex;
VersionOptions: TYPE = DBCommon.VersionOptions;
DBPage: TYPE = DBCommon.DBPage;
CacheHandle: TYPE = DBCache.CacheHandle;
TID: TYPE = DBStorageTID.TID;
-- This is the interface to databases at the level of segments. A database has a
--uniform address space, but within this space live "segments" which are the
--repositories of database pages. Thus it is possible to allocate a page from a
--segment, or free a previously allocated page.
-- To preserve the hierarchical character of the system, this in the only major
--lower-level interface used in the storage level implementation, and is the only
--interface exported by the segment level implementation.
-- Initialization
Initialize: PROC [
nCachePages: NAT, useCacheFile: ROPE,
segmentInitProc: PROC [s: Segment] RETURNS [TID, TID]];
-- Initializes the database system at the segment level and below.
-- Use nCachePages pages for cache size. Call segmentInitProc when creating
-- a new segment.
-- Segment/Transaction interface (closely parallel to DBStorage)
AttachSegment: PROC [
fileName: ROPE, s: Segment, segmentIndex: SegmentIndex,
readonly: BOOL, version: VersionOptions, initializeExistingFile: BOOL,
nBytesInitial, nBytesPerExtent: INT];
EnumerateSegments: PROC [
enumProc: PROC [s: Segment, segmentIndex: SegmentIndex] RETURNS [stop: BOOL]];
OpenTransaction: PROC [
s: Segment, useTrans: Trans, noLog: BOOL] RETURNS [fileChanged: BOOL];
-- Returns TRUE if the file changed since the last time we opened a transaction
-- on that file from client's machine. (Always returns TRUE first time).
GetSegmentInfo: PROC [s: Segment] RETURNS [
filePath: ROPE, number: NAT, trans: Trans,
readOnly: BOOL, nBytesInitial, nBytesPerExtent: INT];
FinishTransaction: PROC [t: Trans, abort: BOOL, continue: BOOL];
RootIndicesFromSegment: PROC [s: Segment] RETURNS [index1, index2: TID];
SegmentFromTID: PROC [tid: TID] RETURNS [s: Segment];
-- "tid" is a tuple ID in an attached segment. Returns the name of the segment.
IsValidTID: PROC [tid: TID] RETURNS [valid: BOOL];
-- "tid" is a tuple ID in an attached segment. Returns TRUE iff a transaction is open
--for that segment.
SegmentIDFromDBPage: PROC [p: DBPage] RETURNS [SegmentID];
-- "p" is a page in an open segment. Returns the first page in the segment.
SegmentIDFromSegment: PROC [s: Segment] RETURNS [SegmentID];
-- s is an attached segment. Returns the first page in the segment.
-- Page allocation interface
AllocPage: PROC [s: SegmentID]
RETURNS [--p--DBPage, --pValidHint--CacheHandle, --cachePage--LONG POINTER];
-- PARAMETERS: s is a SegmentID (a pointer to the head page of a segment).
-- RESULTS: p is a previously unused page within segment s, with pValidHint a cache
--hint and cachePage a cache pointer for it. pValidHint ha a lock count of 1.
-- ERRORS: if s does not identify a segment, if the file representing s is full, or
--if the database address space is full.
-- NOTES: AllocPage does NOT necessarily read the page p from Juniper.
FreePage: PROC [s: SegmentID, freePg: DBPage, freeHint: CacheHandle];
-- PARAMETERS: s is a SegmentID (result of SegmentIDFromDBPage or SegmentIDFromFile),
--and freePg is a page within that segment (with freeHint a cache hint for it). The
--lock count of freeHint is 1.
-- EFFECTS: FreePage makes freePg unused, and freeHint becomes meaningless.
-- ERRORS: if s is not a SegmentID, or if freePg is not in s.
-- NOTES: If references to freePg still exist, they become "dangling". Errors of
--this kind may go undetected, since freed pages are reused.
-- Page access interface
-- Definition: A "valid" cache hint for a DBPage p is a DBCache.CacheHandle for p,
--with a positive lock count. Note that when a cache hint becomes invalid (lock count
--reaches zero), it is an error to use any core location derived from the hint.
ReadPage: PROC [p: DBPage, pHint: CacheHandle]
RETURNS [--pValidHint-- DBCache.CacheHandle, --coreLoc-- LONG POINTER];
-- PARAMETERS: p is a page address in the current database, and pHint is a cache
--hint for it.
-- RESULTS: pValidHint is a valid cache hint for p, and coreLoc is a pointer to the
--data contained on page p. The caller may read data from the page using this
--pointer, for as long as pValidHint has a positive lock count.
-- EFFECTS: the lock count of pValidHint is increased by 1 (the count is implicitly
--zero before the first reference to the page).
-- ERRORS: DBException.Fatal[AllCachePagesLocked] if it is necessary to read p into
--core, and there are no unlocked pages in the cache to read p into.
WritePage: PROC [p: DBPage, pHint: CacheHandle]
RETURNS [--pValidHint-- DBCache.CacheHandle, --coreLoc-- LONG POINTER];
-- The same as ReadPage, except that the caller may also write the data pointed to
--by coreLoc (i.e. it sets the write-dirty bit in pValidHint).
-- ERRORS: DBException.Fatal[AccessDenied] if this page cannot be written back to
--the file system.
UnlockPage: PROC [pValidHint: CacheHandle];
-- EFFECTS: Decrements pValidHint's lock count by one.
-- ERRORS: DBException.InternalBug[AlreadyUnlocked] if the count was already zero.
WriteLockedPage: PROC [pValidHint: CacheHandle];
-- PARAMETERS: pValidHint is a CacheHandle with a positive lock count.
-- EFFECTS: the write-dirty bit of pValidHint is set.
-- ERRORS: If pValidHint's lock count is 0 then DBException.InternalBug is raised.
--If the page is protected from writing (cannot be written back to the file system)
--then DBException.Fatal[AccessDenied] is raised.
-- NOTES: The effect of WriteLockedPage is the same as WritePage; UnlockPage, except
--that the page must be locked beforehand. The effect of WritePage is identical to
--[pValidHint, coreLoc] ← ReadPage[p, pHint]; WriteLockedPage[pValidHint].
LockCount: PROC [p: DBPage, pValidHint: CacheHandle]
RETURNS [lockCount: CARDINAL];
-- PARAMETERS: p is a page address in the current database, and pValidHint is a
--valid cache hint for it.
-- RESULTS: the lock count of page p.
-- ERRORS: DBException.BadOperaton[??] is raised if pHint is not a valid cache
--handle for page p. This includes pHint having a lock count of 0.
-- NOTES: This routine is intended for use in debugging only, especially for
--checking assertions like "p now has lock count 1, so calling UnlockPage will
--release it." Programs should not intentionally lose track of the lock count of a
--page and then use this procedure to release the page.
ObtainCoreLoc: PROC [p: DBPage, pValidHint: CacheHandle]
RETURNS [coreLoc: LONG POINTER];
-- PARAMETERS: p is a page address in the current database, and pValidHint is a
--valid cache hint for it.
-- RETURNS: The core location of the page p.
-- ERRORS: DBException.BadOperaton[??] is raised if pHint is not a valid cache
--handle for page p. This includes pHint having a lock count of 0.
-- NOTES: The parameter pHint is for efficiency, to avoid a hashed lookup when the
--hint is known to be valid. When the validity of the hint is uncertain, ReadPage
--should be used instead of ObtainCoreLoc.
-- Debugging interface
CheckState: PROC [doPrinting, printOnlyLockedPages: BOOL];
-- Checks internal consistency of segment implementation, optionally
--prints to the debug stream.
END.--DBSegment
CHANGE LOG
Created by MBrown on January 4, 1980 3:31 PM
Changed by MBrown on January 14, 1980 2:29 PM
-- Changed module name to conform to Cedar standard.
Changed by MBrown on February 4, 1980 3:44 PM
-- Changed name of GetSegmentID to FileIDToSegmentID; added DBPageToSegmentID.
Changed by MBrown on February 21, 1980 10:20 AM
-- Added procedures ReadPage, WritePage, ... ObtainFile. The intention is to make
--segments a true "level", i.e. the storage level will no longer communicate directly
--with the cache level.
-- Also changed definition of AllocPage to return a locked page.
Changed by MBrown on February 21, 1980 1:38 PM
-- Made AllocPage return the LONG POINTER to the locked page. Added LockCountOfPage.
Changed by MBrown on February 29, 1980 10:33 AM
-- Added OpenDatabase, etc, to complete the isolation between the segment and storage
--levels.
Changed by MBrown on March 3, 1980 1:36 PM
-- Changed CreateDatabase and OpenDatabase to allow root indexes to be created.
Changed by MBrown on April 16, 1980 4:42 PM
-- Changed LockCountOfPage to LockCount, added ObtainCoreLoc.
Changed by MBrown on April 18, 1980 11:34 AM
-- Worked on comments.
Changed by MBrown on June 10, 1980 8:46 PM
-- TID now comes from DBStorageTID.
Changed by MBrown on August 5, 1980 8:49 PM
-- Clarified the specifications of CloseDatabase and CloseCommunication. Responsibility
--for performing the former immediately before the latter is now delegated to the
--client.
Changed by MBrown on August 29, 1980 3:34 PM
-- Added server parm and welcomeText result to OpenCommunication.
Changed by MBrown on September 12, 1980 11:07 AM
-- Added Finalize, added comments about sequencing of Segment interface calls.
Changed by MBrown on December 8, 1980 3:46 PM
-- Added nBytesInitial and nBytesPerExtent parms to CreateSegment.
Changed by MBrown on December 11, 1980 6:54 PM
-- Flushed RegisterUser, added parms to OpenCommunication. Changed Commit to CommitTransaction.
--Flushed SetTransactionNotifyProcedure.
Changed by MBrown on February 26, 1981 9:11 PM
-- Redefined OpenCommunication: server is used to decide what file system to use. Transaction is
--UNSPECIFIED. newTrans parm added.
Changed by MBrown on 19-Jun-81 8:51:33
-- STRING -> Rope.Ref.
Changed by Willie-Sue on June 24, 1982 12:12 pm
-- Rope.Ref => Rope.ROPE
Changed by MBrown on November 24, 1982 4:18 pm
-- Changes to enable independent segments.
Changed by Cattell on January 16, 1983 12:41 pm
-- Added useCacheFile arg to Initialize.
Changed by Willie-Sue on February 3, 1983 10:38 am
-- Added noLog arg to OpenTransaction.