stabletable/src/StableTbl.ig


Copyright (C) 1994, Digital Equipment Corp.

GENERIC INTERFACE StableTbl(Tbl, Key, Value);
A StableTbl.T is like a Table.T, except that operations on the table are logged to stable storage for reliability. The Tbl interface should be an instantiation of the generic Table interface, where Key and Value are the interfaces used to produce that instantiation.

IMPORT OSError, SmallDB;

TYPE
  T <: Public;
  Public = Tbl.T BRANDED OBJECT METHODS
    (* "Tbl.Default"  methods that require disk operations *)
    init(sizeHint: CARDINAL := 0): T RAISES { OSError.E };
    put(READONLY k: Key.T; READONLY v: Value.T): BOOLEAN RAISES { OSError.E };
    delete(READONLY k: Key.T; VAR v: Value.T): BOOLEAN RAISES { OSError.E };

    (* new methods *)
    checkpoint() RAISES { OSError.E };
    close() RAISES { OSError.E };
    checkpointSize(): CARDINAL;
    logSize(): CARDINAL;
    status(): TEXT;
  END;

PROCEDURE New(dir: TEXT; sizeHint: CARDINAL := 0): T
  RAISES { OSError.E, SmallDB.Failed };
The call NEW(dir, sizeHint) recovers a stable table from the directory named dir. If the table does not yet exist, a new one is created using sizeHint as described in the Table interface. It is an unchecked error for more than one client to create or use a stable table on the same directory at one time.

The usual operations described in the Table interface are available. Each operation that changes the table is recorded to a stable log. In the event of a crash, this log is read to recover the last good state of the table. The methods init, put, and delete are redeclared for a StableTbl.T because they can raise OSError.E.

The time required to recover in the event of a crash is proportional to the size of the log. To reduce recovery time, the client can call checkpoint. This writes a snapshot of the table to stable storage and erases the log.

When the client is finished using a stable table, its close method should be called to close the stable storage associated with the table in an orderly manner.

The checkpointSize and logSize methods return the sizes of the latest checkpoint and log files (in bytes).

The status method returns the status of the stable table in human-readable form.

END StableTbl.