-- [Indigo]<Grapevine>VM>VMDefs.mesa

-- Transport Mechanism - DEFS for simulated virtual memory --

-- Andrew Birrell   8-Feb-80 10:29 --
-- Roy Levin      2-Nov-81 16:07:14 --


VMDefs: DEFINITIONS =

  BEGIN


  -- Types --

  CacheIndex: TYPE = [0..256);
  -- implementation limit on number of pages in cache.

  Page: TYPE = POINTER TO PageContents;
  PageContents: TYPE = RECORD [
    SELECT OVERLAID * FROM
      words => [words: ARRAY PageIndex OF WORD],
      bytes => [bytes: PACKED ARRAY PageByteIndex OF [0..256)],
      chars => [chars: PACKED ARRAY PageByteIndex OF CHARACTER],
      ENDCASE];

  PageNumber: TYPE = [0..LAST[CARDINAL]);
  -- PageNumber = 0 for the first data page of a file.
  -- Note:  Notwithstanding this declaration, the implementation limits the maximum
  -- value of PageNumber to be 77777B.

  pageSize: CARDINAL = 256;
  -- the maximum number of words in a data page.

  pageByteSize: CARDINAL = 512;
  -- the maximum number of bytes in a data page.

  PageIndex: TYPE = [0..pageSize);
  -- PageIndex = 0 for the first data word of a page of a file.

  PageByteIndex: TYPE = [0..pageByteSize);
  -- PageByteIndex = 0 for the first data byte of a page of a file.

  PageAddress: TYPE = RECORD [file: FileHandle, page: PageNumber];

  FullAddress: TYPE = RECORD [page: PageAddress, word: PageIndex];
  -- Defines a data word within a file; the earliest data word occurs at page=0, word=0.

  Position: TYPE = RECORD [page: PageNumber, byte: PageByteIndex];
  -- Defines a data byte index within a file; the earliest data byte occurs at page=0,
  -- byte=0.


  -- Global control --

  InitializeVM: PROCEDURE [min, max: CacheIndex, numOps: CARDINAL _ 20];
  -- Specifies number of pages to be allowed in cache; number may be reduced from in
  -- response to requests for storage for other reasons, but will not be allowed to drop
  -- below min.  "numOps" is the maximum number of (local) disk operations that can be
  -- in progress simultaneously.  This must be called before any other procedure in
  -- VMDefs. It is assumed that during InitializeVM no attempt is made to access
  -- other procedures of the virtual memory system.

  FinalizeVM: PROCEDURE;
  -- Tidies up and shuts down the virtual memory system.  If any files remain open,
  -- an error is raised.  It is assumed that during FinalizeVM no attempt is made to
  -- access other procedures of the virtual memory system.


  -- File system access --

  FileSystemType: TYPE = {Alto, IFS, Juniper};

  FileSystem: TYPE = POINTER TO FSInstance;
  FSInstance: TYPE;

  FSAlto: FileSystem = NIL;

  Login: PROCEDURE [system: FileSystemType,
    server, userName, password, secondaryName, secondaryPassword: STRING _ NIL]
    RETURNS [FileSystem];
  -- Initiates activity with a file system of the indicated sort using the indicated
  -- server, and supplies user's credentials.  The FileSystem returned
  -- is subsequently supplied to OpenFile to identify the file system (see below).
  -- The precise semantics of this procedure are file system dependent:
  --   Alto	This operation has no effect and can be omitted.
  --   IFS	Login is mandatory.  The userName and password are passed
  --		to the indicated server (which cannot be defaulted) for validation.
  --   Juniper	Login is mandatory.  The userName and password are passed to the
  --		indicated server (or nearest one, if defaulted) for validation.  If
  --		the login attempt succeeds, the FileSystem returned implicitly
  --		identifies a transaction under which subsequent file operations will
  --		be performed.  It is permissable to have multiple FileSystems for
  --		Juniper, which represent multiple transactions.

  UnableToLogin: ERROR [reason: Problem];
  -- raised by Login.

  Logout: PROCEDURE [FileSystem];
  -- Terminates activity with the indicated file system.  The precise semantics of
  -- this procedure are file system dependent:
  --    Alto	This operation has no effect and can be omitted.
  --    IFS	All files must previously have been closed.
  --    Juniper	An implicit CheckpointTransaction occurs.
  -- After Logout, the FileSystem is no longer valid and must not be reused.

  Error: ERROR [reason: Problem];
  -- Error conditions that are largely independent of the specific operation are
  -- reported by this signal.  It can be raised by any of the file system access
  -- procedures defined in this interface or by ReadPage, Wait, StartWait, or
  -- MarkStartWait.  The state of open files on the file system's backing store is
  -- file system dependent; local (cached) pages of the files are unaffected.  The
  -- appropriate recovery strategy depends upon the specific problem; see below.

  Problem: TYPE = {ok, io, resources, credentials, other};
  -- The general interpretations of these problems are as follows:
  --    ok		(For internal convenience; never actually raised).
  --    io		An I/O failure has occurred.  For the local (Alto) file system,
  --			this indicates an unrecoverable disk error.  For remote file
  --			systems, a communication failure or other problem (e.g., server
  --			crash) has rendered the file system unavailable.  The use of
  --			AbandonFile to cleanup after this error is encouraged; in
  --			particular, subsequent page access operations (with certain
  --			explicitly noted exceptions, e.g., UsePage), CloseFile, or
  --			AbandonFile are likely to raise this signal again.
  --    resources	The file system cannot perform the requested operation because
  --			of some sort of resource constraint.  For the local (Alto) file
  --			system, this indicates the disk is full.  For remote file
  --			systems, a storage quota may have been reached, or the storage
  --			resource may have been exhausted.
  --    credentials	The file system has rejected the requested operation on the
  --			basis of access controls.  The credentials presented at Login
  --			time were insufficient to permit the attempted operation.
  --	other		This is a placeholder whose meaning is not specified.

  CheckpointTransaction: PROCEDURE [FileSystem];
  -- If the argument FileSystem does not identify a Juniper file system, this operation
  -- has no effect.  Otherwise, the caller is suspended until all previously initiated
  -- writes completed, at which time they become committed.  The underlying transaction
  -- remains valid, and open files remain open.

  AbortTransaction: PROCEDURE [FileSystem];
  -- If the argument FileSystem does not identify a Juniper file system, this operation
  -- has no effect.  Otherwise, any writes started since the last CheckpointTransaction
  -- are canceled.  Any files opened as part of this transaction are automatically
  -- closed.

  TransactionError: ERROR [reason: TransactionProblem];
  -- raised by CheckpointTransaction (and therefore implicitly by Logout).

  TransactionProblem: TYPE = {ok, aborted, brokenReadLock, other};


  -- File handling --

  FileHandle: TYPE = POINTER TO FileObject;
  FileObject: TYPE;

  Percentage: TYPE = [0..100];

  FileTime: TYPE = LONG CARDINAL;
  -- times are expressed in seconds since midnight, January 1, 1901 GMT.  Note that
  -- this is compatible with the standard Time and TimeDefs interfaces.

  defaultTime: FileTime = 0;

  OpenOptions: TYPE = {old, oldReadOnly, new, oldOrNew};
  -- defines how a file will be opened, as follows:
  --  old - file must exist, read/write/append
  --  oldReadOnly - file must exist, only read allowed
  --  new - file must not exist, read/write/append
  --  oldOrNew - created if needed, read/write/append

  OpenFile: PROCEDURE [
    system: FileSystem _ FSAlto, name: STRING, options: OpenOptions _ oldReadOnly,
    cacheFraction: Percentage _ 0]
    RETURNS [FileHandle];
  -- the file 'name' is assumed to be interpretable by the FileSystem 'system', which
  -- is requested to open the file under the conditions specified by 'options'.
  -- 'cacheFraction' suggests the proportion of the cache that should be allocated
  -- for this file.

  CantOpen: ERROR [reason: AccessFailure];
  -- raised by OpenFile.

  AccessFailure: TYPE =
  {ok, io, notFound, alreadyExists, accessDenied, illegalFileName, other};
  -- 'ok' and 'io' are for internal use only; they are never actually raised.
  -- 'notFound' applies if 'options' is either 'old' or 'oldReadOnly' and the file
  -- cannot be found.  'alreadyExists' applies if 'options' is 'new' and the file
  -- already exists.  'accessDenied' applies if granting access would violate
  -- the file system's guarantees of protection or file integrity.  (This may
  -- mean that the file is temporarily unavailable or that the file system
  -- considers the credentials supplied by Login and 'options' to be incompatible.)
  -- 'illegalFileName' applies if the file system rejects the file name on
  -- syntactic grounds.

  GetOpenFileParameters: PROCEDURE [FileHandle]
    RETURNS [system: FileSystem, options: OpenOptions, cacheFraction: Percentage];
  -- returns the values of the indicated parameters supplied at OpenFile time.

  CloseFile: PROCEDURE [FileHandle];
  -- The FileHandle will no longer be used.  An error will be raised if any unreleased
  -- pages remain for this file.  Calls StartFile followed by WaitFile.

  GetFileSystem: PROCEDURE [file: FileHandle] RETURNS [FileSystem] =
  -- returns the 'system' argument supplied to OpenFile at the time that it returned
  -- the indicated FileHandle.
    INLINE {RETURN[GetOpenFileParameters[file].system]};

  DestroyFile: PROCEDURE [FileHandle];
  -- Calls CloseFile, then deletes the file from the file system.

  AbandonFile: PROCEDURE [FileHandle];
  -- The FileHandle will no longer be used.  Any unreleased pages of the file will
  -- be forcibly released.  Dirty pages in the cache are not guaranteed to
  -- reach the backing file.  This procedure is intended to be used to clean up after
  -- Error[io] has been raised.

  GetFileLength: PROCEDURE [FileHandle] RETURNS [Position];
  -- Returns the page and byte number of the byte one beyond the last byte of the file.
  -- For an empty file, this is [0, 0]; for a file with 512 data bytes, this is [1, 0];
  -- for a file with 612 data bytes, this is [1, 100].

  SetFileLength: PROCEDURE [file: FileHandle, position: Position];
  -- Sets the length of the file such that the Position argument refers to the byte
  -- one beyond the last byte of the file.  SetFileLength performs atomic extension of
  -- the file if the new length implies a transfer of at most one page and the data
  -- for the extension is present in the cache.  Otherwise, if the file is implicitly
  -- lengthened, new bytes have undefined content.

  StartFile: PROCEDURE [FileHandle];
  -- Initiates transfers for all pages of the file marked as dirty in the cache.

  WaitFile: PROCEDURE [FileHandle];
  -- The caller is suspended until all previously initiated transfers on this file
  -- have completed.  This call may raise the signal CantWriteBackingStore.

  GetFileTimes: PROCEDURE [file: FileHandle]
    RETURNS [read, write, create: FileTime];
  -- returns the associated times for the given file.

  SetCreationTime: PROCEDURE [file: FileHandle, create: FileTime _ defaultTime];
  -- sets the creation time for the indicated file.  If the time is defaulted, it is
  -- set to the current time.



  -- Access to pages --

  -- The following procedures provide a means of accessing files similar to that
  -- available in an integrated virtual memory.  While a page of the virtual memory
  -- is swapped in to physical memory, it is shared by all its users.  Each page is
  -- locked in physical memory while anyone is using it.  Anyone altering the contents
  -- of a page must notify this fact before releasing the page.

  -- If the page being manipulated is associated with a file that is part of a
  -- transaction, then operations that write the page to the file do not become
  -- permanent until the transaction is "committed" (see CheckpointTransaction and
  -- Logout, above).  The comments below define the moment of committal for
  -- pages in files that are not part of a transaction, which includes all files on the
  -- local Alto disk.

  LookAheadCount: TYPE = CacheIndex;

  ReadPage: PROCEDURE [addr: PageAddress, lookAhead: LookAheadCount _ 0]
    RETURNS [Page];
  -- Read specified page, waiting until the contents are available, and possibly
  -- initiating read-ahead.  The memory is allocated by the virtual memory system, and
  -- is available to the caller until he calls ReleasePage with this page.  Multiple
  -- users of the same page receive the same 'Page' value.   Reading beyond the end
  -- of the file is not allowed.  If an unrecoverable error has occurred when reading
  -- the data from the file, and has not been cleared (see UsePage), the signal
  -- CantReadBackingStore is raised.

  StartReading: PROCEDURE [addr: PageAddress, lookAhead: LookAheadCount _ 0];
  -- Initiates reading the specified page, and "lookAhead" extra pages.  addr.page
  -- may legitimately fall in the range [0..filesize).

  UsePage: PROCEDURE [addr: PageAddress] RETURNS [Page];
  -- Return specified page, but its contents are undefined; no read operation occurs.
  -- The memory is allocated by the virtual memory system, and is available to the
  -- caller until he calls ReleasePage with this page.  Multiple users of the same page
  -- receive the same 'Page' value.   addr.page may legitimately fall in the range
  -- [0..filesize].  This call clears any unrecoverable errors which had previously
  -- occurred when reading the data for this page from the file.

  AllocatePage: PROCEDURE RETURNS [Page];
  -- Allocate page in memory with undefined contents.  The memory is allocated by the
  -- virtual memory system, and is available to the caller until he calls ReleasePage
  -- with this page.  Before this page can passed to MarkStart or MarkStartWait, it must
  -- be associated with an address by passing it to RemapPage.

  RemapPage: PROCEDURE [page: Page, addr: PageAddress];
  -- The given page is now to be considered as the contents of the address "addr".  It
  -- is required that there be no other user of "page", and that there be no user of
  -- "addr".  addr.page may legitimately fall in the range [0..filesize].  This call
  -- clears any unrecoverable errors which had previously occurred when reading the data
  -- for "addr" from the file.

  UnmapPage: PROCEDURE [Page];
  -- The given page is disassociated from any backing storage.  It is required that
  -- there be no other user of the argument Page.

  PageInCache: PROCEDURE [PageAddress] RETURNS [BOOLEAN];
  -- This procedure permits clients to optimize performance by testing whether a ReadPage
  -- of the argument PageAddress is likely to be fast.  A TRUE result from this procedure
  -- means a subsequent ReadPage will probably not require physical I/O.

  Mark: PROCEDURE [Page];
  -- The contents of the given page have been altered.  If the page is associated
  -- with a backing file page and is subsequently removed from the in-core cache, the
  -- new data will be written to the file.  The implicitly associated PageNumber must be
  -- in the range [0..filesize).  It is an error to invoke this operation on a page
  -- that is associated with a read-only file.

  MarkStart: PROCEDURE [Page];
  -- The contents of the given page have been altered and are to be written to the
  -- associated page of backing file (it is an error to perform this operation on a page
  -- that has no backing storage).  MarkStart initiates the transfer of the data
  -- to the file, but does not wait for it to complete.  The implicitly associated
  -- PageNumber may legitimately fall in the range [0..filesize].  If it equals
  -- filesize, the file is implicitly extended during this call, although this fact may
  -- not yet be recorded on stable storage.  It is an error to invoke this operation
  -- on a page that is associated with a read-only file.

  MarkStartWait: PROCEDURE [Page];
  -- The contents of the given page have been altered and are to be written to the
  -- associated page of backing file (it is an error to perform this operation on a page
  -- that has no backing storage).  MarkStartWait initiates the transfer of the data
  -- to the file, and waits for it to complete.  The implicitly associated
  -- PageNumber may legitimately fall in the range [0..filesize].  If it equals
  -- filesize, the file is implicitly extended during this call.  This call may raise
  -- the signal CantWriteBackingStore.  It is an error to invoke this operation
  -- on a page that is associated with a read-only file.

  Start: PROCEDURE [Page];
  -- If the contents of the given page have been marked as dirty, Start initiates the
  -- transfer of the data to the file (it is an error to perform this operation on a
  -- page that has no backing storage).  The implicitly associated PageNumber may
  -- legitimately fall in the range [0..filesize].  If it equals filesize, the file is
  -- implicitly extended during this call.

  StartWait: PROCEDURE [Page];
  -- If the contents of the given page have been marked as dirty, StartWait initiates
  -- the transfer of the data to the file, and wait for it to complete (it is an error
  -- to perform this operation on a page that has no backing storage).  The implicitly
  -- associated PageNumber may legitimately fall in the range [0..filesize].  If it
  -- equals filesize, the file is implicitly extended during this call.  This call may
  -- raise the signal CantWriteBackingStore.

  Wait: PROCEDURE [Page];
  -- If a transfer of the data to the file has previously been initiated, then wait
  -- for it to complete.  This call may raise the signal CantWriteBackingStore.

  Release: PROCEDURE [Page];
  -- The caller is no longer reading or writing the page of memory indicated, although
  -- others may be doing so.  The data contents of the page are preserved, although
  -- they are not necessarily written to the file unless MarkStart or MarkStartWait has
  -- previously been called for this page.

  Deactivate: PROCEDURE [Page];
  -- This operation is logically equivalent to Release, but additionally suggests to
  -- the implementation that the argument Page be removed from the in-core cache.
  -- Deactivate can produce better cache performance during extended "streaming"
  -- operations.

  PageToPageAddress: PROCEDURE [Page] RETURNS [PageAddress];
  -- delivers the PageAddress corresponding to Page.  The page must be associated with
  -- a backing storage location.


  -- Errors --

  CantWriteBackingStore: ERROR [badAddress: PageAddress, badPage: Page];
  -- the data for this page could not be written to the file, because of persistent
  -- errors;  this is raised if the user waits for the page to reach the file.

  CantReadBackingStore: ERROR [badAddress: PageAddress];
  -- the data for this page could not be read from the file; this is raised whenever
  -- the user asks for the data (see ReadPage and UsePage).

  END.