-- Store>TransactionState.mesa
-- Last edited by Gobbel on January 6, 1981  2:41 PM
-- This interface supplies operations for modifying the transaction data base
-- for use by higher-level transaction-related software (FileMgr,
-- TransactionMgr, VMMgr).

DIRECTORY
  File USING [ID, PageCount, PageNumber, Type],
  Space USING [Handle, WindowOrigin],
  System USING [VolumeID],
  Transaction USING [Handle];

TransactionState: DEFINITIONS =
BEGIN

--  The Log for a transaction is an "undo log".  Thus, a LogEntry records
-- actions to be done if the transaction aborts, or if by crash recovery for
-- uncommitted transactions.  For example, if a file was made permanent in a
-- transaction, a makeTemporary entry would be recorded the transaction's Log.

--  Changing the format of a LogEntry (in a non-backward compatible manner)
-- invalidates all existing Transaction Log Files.  If you do change the
-- format, you must change TransactionInternal.stateFormatVersion.

LogOp: TYPE = MACHINE DEPENDENT
  {create(0), delete(1), makeMutable(2), makeTemporary(3), move(4),
  setContents(5), shrink(6)};

LogEntryPtr: TYPE = LONG POINTER TO LogEntry;
LogEntry: TYPE = MACHINE DEPENDENT RECORD [
  -- MACHINE DEPENDENT so that format endures over compiler changes.
  logEntry(0): SELECT operation(0:0..2): LogOp FROM
    create => [
      fill(0:3..15): [0..17777B] ← 0,
      id(1:0..79): File.ID,
      volume(6:0..79): System.VolumeID,
      size(11:0..31): File.PageCount,
      type(13:0..15): File.Type],
    delete, makeMutable, makeTemporary => [
      fill(0:3..15): [0..17777B] ← 0,
      id(1:0..79): File.ID,
      fill1(6): CARDINAL ← 0],
    move => [
      fill(0:3..15): [0..17777B] ← 0,
      id(1:0..79): File.ID,
      fill1(6): CARDINAL ← 0,
      volume(7:0..79): System.VolumeID],
    setContents => [
      makePermanent(0:3..3), makeImmutable(0:4..4): BOOLEAN ← FALSE,
      fill(0:5..15): [0..3777B] ← 0,
      id(1:0..79): File.ID,
      fill1(6): CARDINAL ← 0,
      base(7:0..31): File.PageNumber,
      size(9:0..31): File.PageCount],
	-- if necessary, grow file so that file.size >= base+size.
    shrink => [
      fill(0:3..15): [0..17777B] ← 0,
      id(1:0..79): File.ID,
      fill1(6): CARDINAL ← 0,
      size(7:0..31): File.PageCount] -- shrink file to have size pages.
    ENDCASE];

SpaceNodePtr: TYPE = LONG POINTER TO SpaceNode;
SpaceNode: TYPE = RECORD [
  -- list element for a Space that is part of a transaction.
  handle: Space.Handle,
  window: Space.WindowOrigin, -- (scratch storage for Abort processing)
  nextSpace: SpaceNodePtr];


ReleaseTransaction: PROCEDURE [transaction: Transaction.Handle];
-- Marks this transaction no longer in use (i.e. it has been Committed or
-- Aborted).  All updates to client files must have been done or undone on
-- the disk before this routine is called!

RecordCommit: PROCEDURE [transaction: Transaction.Handle];
-- Marks the transaction committed (and records the fact on the disk).
-- All updates to client files must have been forced out to the disk before
-- this routine is called!

AddToTransaction: PROCEDURE
  [transaction: Transaction.Handle, space: Space.Handle];
-- Adds this space to the list of spaces involved in the transaction.
-- May raise Transaction.InvalidHandle.
-- The client must assure that the space is not already involved in the
-- transaction!

WithdrawFromTransaction: PROCEDURE
  [transaction: Transaction.Handle, space: Space.Handle];
-- Withdraws this space from the list of spaces involved in the transaction.
-- May raise Transaction.InvalidHandle.
-- The client must assure that the space is involved in the transaction!

InitializeStateA: PROCEDURE[];
-- Creates SimpleSpaces.  Must be called before VMMgr is initialized.

InitializeStateB: PROCEDURE[];
-- Initializes databases.  Must be called after VMMgr is initialized.

Log: PROCEDURE
  [transaction: Transaction.Handle, op: LogEntryPtr, fileOps: FileOps];
-- Records one "undo" operation in the transaction's Log File.
-- May raise Transaction.InvalidHandle, Volume.InsufficientSpace.
-- If a higher-level operation requires several LogEntrys, they must be
-- logged in reverse of the order in which these "undo" actions must be done
-- (if the transaction aborts).  Note that the files operated on by fileOps
-- must not be the file being logged.  Since this procedure is called from
-- within the FileImpl monitor, it may  not be called from any system
-- component at a level higher than the FileMgr.

FileOps: TYPE = RECORD [
  CreateFile: PROCEDURE [size: File.PageCount, type: File.Type]
    RETURNS [file: File.ID],
    -- Creates file of given size and type on the system volume.
    -- May raise Volume.InsufficientSpace.
  MakeFilePermanent: PROCEDURE [file: File.ID],
    -- Makes the file permanent.
    -- If file is unknown, you will wake up in the debugger.
  SetFileSize: PROCEDURE [file: File.ID, size: File.PageCount]];
    -- Adjusts file to have size pages.
    -- May raise Volume.InsufficientSpace.  If file is unknown, you will wake
    -- up in the debugger.

NoMoreOperations: PROCEDURE [transaction: Transaction.Handle]
  RETURNS [spaceList: SpaceNodePtr];
-- Checks out this transaction to Abort or Commit.  Prevents further client
-- operations.  spaceList is the head of a list of spaces involved in
-- transaction.  Raises Transaction.InvalidHandle if the transaction has
-- already been checked out by some other process.

END.
LOG
June 10, 1980  9:37 PM	Gobbel
Created file from TransactionInternal.

August 15, 1980  1:17 PM	Knutsen
Added comments describing clients.

September 2, 1980  2:56 PM	Knutsen
Renamed module from SpecialTransacton to TransactionState.  Added disabled,  ReleaseTransaction, RecordCommit, InitializeStateA/B, NoMoreOperations, ProcessLog (temorary!).  Deleted GrowLog.  Added fileOps to Log.

September 8, 1980  5:58 PM	Gobbel
Added WithdrawFromTransaction.

December 31, 1980  11:13 AM	Gobbel
Changed capabilities in log file entries to IDs.