InOS.WF4: PROC [s: STRING, a,b,c,d: LONG POINTER];

InOS.WF: PROC [s: STRING, a,b,c,d: LONG POINTER ← NIL];

InOS.WFN: PROC [s: STRING, array: DESCRIPTOR FOR ARRAY OF LONG POINTER];

InOS.WFC: PROC [CHARACTER];

InOS.WFCR: PROC;

InOS.SetCode: PROC[CHARACTER, PROC[LONG POINTER, STRING, PROC[CHARACTER]]];

InOS.SetWriteProcedure: PROC [PROC[CHARACTER]] RETURNS [PROC[CHARACTER]];

InOS.WFError: ERROR;

The remainder of this interface will be of interest only to those providing new implementations of ClassInscript and/or Interminal. It supplies procedures for dealing with the keyboard hardware, the real time facilities, and the high-priority process activities required to provide the keyboard "interrupt" process (supplied by InterminalImpl.)

These functions merely return the fixed long addresses that point to the states of the keyboard, mouse, and cursor. They appear here because Pilot supplies functions obscuring the absolute locations, while the Alto world assumes that the client knows the addresses.

Similarly, the following functions return the current values of the high-resolution interval timer (ReadFastClock), and the long-term seconds-resolution clock (GetTimeParameters). The latter function also returns a value corresponding to the number of interval-timer ticks in a second; in addition, it should perform any initialization required to perform these two functions (an issue in the current Alto implementation).

SetupTerminalHandler must perform any OS-dependent activities related to shutting off any existing terminal handlers and starting ours. WaitForTick provides a non-busy wait until the next process-scheduling interval (approx. 60 hz.). MakeCallerResident must lock the code segment of the caller into physical memory.


ClassInscript and Interminal

The ClassInscript interface provides an Inscript object, whose function is to record variable-length entries in a disk file, and to supply these entries on request at a later time. In addition, the Inscript (with the help of its clients) periodically records sufficient information to allow the current output position to be reestablished after a system crash or other uncontrolled termination of the package. Beyond that, the Inscript knows little of the semantics of the entries it records. For the courageous implementor, there follows a brief description of the ClassInscript interface. Following that is an even briefer exposition of the current implementation.

Data Types

An Inscript object represents the inscript file as a whole, along with all the operations pertaining to it. The InscriptPageDescriptor describes a particular page within the file, and a position within that page; there may be more than one of them. It does not supply any operations. In retrospect, probably the InscriptPageDescriptor should become the Inscript object. This would reduce considerably the clumsiness of some of the following specifications.

There are two kinds of Inscript clients; those who wish to record into the inscript -- recording clients -- and those who wish to read entries from them -- plain old clients. At present there is but one recording client for an inscript, although that is not a requirement. Recording clients will typically wish to read as well.

An InscriptPageNumber is a "virtual page number" of a page in the Inscript file.

During initialization, the recording client must supply a COmProc and a KEyProc to assist in reestablishing the current "end of file" position within the inscript file. KEyProc should assume that descriptor is positioned at the beginning of a page, and should extract an OrderKey from that page (this clearly requires that the client must record an OrderKey at a known place within each page as it writes the page.) COmProc, given two OrderKeys, should return TRUE iff a is "less than" b. In the Increek implementations, OrderKeys are EventTimes. The Increek implementation knows nothing about OrderKeys except their size.

In order to read entries from the inscript, the client must supply a ReadAssignment procedure. Its job is to coerce the LONG POINTER argument, assumed to denote an entry of interest to the client, into a comprehensible data type, determine the entry's length, copy the entry to a new location if desired, and return the length of the entry to the caller, for use in advancing to the next entry..

WaitMode is used in the primitive WaitForEntry function used to implement the waiting activities in ClassIncreek.GetAction. Its use is described in detail in the Increek section.

Procedures

NewStdInscript creates an Inscript using the standard implementation, discussed below. In addition to the obvious parameters, initializeFile will force a reinitialization of the inscript file even if it already exists, the inscript file will contain 2^lnFileSize data pages, and the inscript history will be discarded in groups of 2^lnGroupSize pages to make room for new entries. The Release operation cleanly terminates an input session (no one calls this one, in current implementations.) GetPageLimits returns the "virtual page numbers" of the pages that currently exist within the inscript file. Functions like ClassIncreek.SetAtTime use this information to initialize their search activities.

An InscriptPageDescriptor, when created, does not refer to any inscript page; other operations make it valid. CopyPageDescriptor copies the information of one descriptor into another, maintaining any necessary internal reference counts (don't perform this function any other way.) ReleasePageDescriptor discards one.

Using the KEyProc and the COmProc, the ClassInscript implementation must establish a valid output position when the Inscript object is created. Subsequently, the only valid recording operations are SetWritePage and WriteEntry.

WriteEntry records the value of the entry array into the next available locations in the current page (using internally maintained page descriptors), failing if there is not enough room. The recording client must then call SetWritePage in order to move on. Things are done this way so that the client can record per-page information (e.g., the page's OrderKey) at the beginning of each page. After initialization, the client should call WriteEntry without any initial call to SetWritePage, and the initialization must take care of guaranteeing that this works -- the output position must be set at "end of file".

SetWritePage will advance to the next "virtual" page, increasing the value of GetPageLimits[...].latestPage by one, and possibly increasing ditto.earliestPage, thus destroying some history. It will fail only under the circumstances (which should be made vanishingly unlikely) that no physical page in the inscript file is available for use. On return, the page descriptor will represent the first data position within the new page.

To read from the inscript, a client performs ReadEntry operations, supplying a ReadAssignment procedure in order to interpret the entries and determine their length. When ReadEntry fails, no more entries remain in the current page; the client should next call SetPage or AdvancePage. Again, this is done to allow the client to do something special at page boundaries. If the InscriptPageDescriptor's page disappears to make way for new entries, ReadEntry will raise InscriptError[code: entryOutOfBounds].

SetPage adjusts its InscriptPageDescriptor to the beginning of the indicated "virtual" page, failing if that page no longer exists or doesn't exist yet. AdvancePage performs SetPage of "current plus one." If AdvancePage fails, it is because no further entries exist in the file. The client might then call WaitForEntry, which will return only if a timeout condition (described in the Increek section) is satisfied, or if one or more new entries have been added to the inscript since the operation was invoked.

In the existing package, InscriptImplAlto and InscriptImplPilot provide two functionally equivalent implementations of ClassInscript. InterminalImpl acts as the recording client, polling the terminal hardware once a tick and recording any changes it sees. This implementation records its Actions into a disk file that behaves as a large ring buffer, filling seldom more than one Alto-sized page per minute under normal conditions. Thus Actions are remembered for quite some time, but not indefinitely (the standard Increek uses a 128 page file.) Both implementations run the recording client at high priority. They both lock inscript pages into memory to prevent page fault delays. They seem to perform efficiently, without losing events. They are monitored so that clients from more than one process can access their inscripts.

The interfaces were designed so that other implementations of Inscripts could be provided, for instance to immutably record user Actions, possibly condensed (retaining fewer actions), to supply an application with Actions from a source other than the attached terminal, etc. These possibilities are discussed in more detail in the design document cited as a reference.