[Indigo]<Mesa>Doc>System>Modules.bravo!1

Page Numbers: Yes First Page: 41 X: 527 Y: 10.5"
Margins: Binding: 13
Odd Heading: Not-on-first-page

Alto/Mesa Modules

Even Heading:

Alto/Mesa Modules

Alto/Mesa Modules
October 1980

This section documents the operations required to manipulate modules at a more detailed level than provided by the language. It is intended for experienced programmers who have a genuine need to manipulate low level system structures. See FrameDefs for further details.

Global Frames

A GlobalFrame is the implementation of the PROGRAM language construct. All manipulation of GlobalFrames is done using GlobalFrameHandles.

GlobalFrameHandle: TYPE = POINTER TO GlobalFrame;

GlobalFrame: TYPE = RECORD [. . .];

The procedures which manipulate global frames are:

GlobalFrame: PROCEDURE [link: UNSPECIFIED] RETURNS [GlobalFrameHandle];

Returns the GlobalFrameHandle corresponding to link, which is interpreted as a control link; it should be either a PROCEDURE, POINTER TO FRAME or PROGRAM. If link is not a valid control link, then either the signal InvalidGlobalFrame or UnboundProcedure will be raised (see the section on Traps for a description of UnboundProcedure).

ValidateGlobalFrame: PROCEDURE [UNSPECIFIED];

Checks to see that the parameter points to a valid global frame; InvalidGlobalFrame is raised if not. Used to check the validity of GlobalFrameHandle parameters by system procedures such as GlobalFrame.

InvalidGlobalFrame: SIGNAL [frame: UNSPECIFIED];

Indicates that frame does not point to a valid global frame.

EnumerateGlobalFrames: PROCEDURE [
proc: PROCEDURE [GlobalFrameHandle] RETURNS [BOOLEAN]]
RETURNS [GlobalFrameHandle];

Calls proc once for each global frame that currently exists. If proc returns TRUE, EnumerateGlobalFrames returns the GlobalFrameHandle of the last frame processed. If all global frames have been processed, NullGlobalFrame is returned.

Warning: If new modules are created while EnumerateGlobalFrames is in control, it is not guaranteed that they will be included in the sequence of GlobalFrameHandles passed to proc.

Frames

A Frame is the implementation of the PROCEDURE language construct. All manipulation of Frames is done using FrameHandles.

FrameHandle: TYPE = POINTER TO Frame;

Frame: TYPE = RECORD [. . .];

Frames may be validated by calling:

ValidateFrame: PROCEDURE [UNSPECIFIED];

Checks to see that the parameter points to a valid frame; InvalidFrame is raised if not.

InvalidFrame: SIGNAL [frame: UNSPECIFIED];

Indicates that frame does not point to a valid frame.

Module Creation / Deletion

The following procedures allow the programmer explicit control over the creation and deletion of modules. NewConfig and RunConfig provide an interface for loading configurations. The language construct NEW should be used for making copies of modules. UnNew and UnNewConfig allow the deletion of previously loaded modules and configurations. SelfDestruct allows a module to UnNew itself and return to its caller. These operations are defined in FrameDefs.

NewConfig: PROCEDURE [name: STRING];

Loads the Bcd contained in the file name. A configuration loaded in this way can be started only by start traps or binding to and starting a frame or PROGRAM which it exports.

LoadConfig: PROCEDURE [name: STRING] RETURNS [PROGRAM];

Loads the Bcd contained in the file name but does not start it. It returns the configurations control module (or NIL if there is none). Note that this will not handle configurations whose control modules take parameters.

RunConfig: PROCEDURE [name: STRING];

Like NewConfig, except that the control modules of the configuration will be started if there are any.

Warning: a StackError will result if a control module requires parameters.

UnNewConfig: PROCEDURE [frame: GlobalFrameHandle];

Deletes all global frames that are a part of the configuration containing frame, as well as all copies of those frames. Frees the storage for the global frames (to the segmentation machinery if it was obtained from there, or to the frame heap), and frees all the code segments.

UnNew: PROCEDURE [frame: GlobalFrameHandle];

Deletes the global frame pointed to by frame. Returns the global frame to the frame heap (if the frame was allocated from that heap). Deletes the code segment of the frame if no other global frames share it.

Warning: there is no check for references that are bound to the module being deleted.

The language construct NEW and the operation UnNew should be used for creating and destroying copies of modules. They are relatively inexpensive operations, and provide facilities for using module instances as objects. NewConfig and UnNewConfig on the other hand, are relatively expensive operations, and should only be used to add or remove configurations which are relatively static.

SelfDestruct: PROCEDURE;

UnNews the module of the caller, and returns to its caller’s caller.

NoGlobalFrameSlots: SIGNAL;

Indicates that there is no room in the Global Frame Table when either NewConfig or RunConfig have been called or the language construct NEW has been invoked.

Fine point: global frames for single modules (and copies) are allocated from the frame heap. Other configurations allocate their global frames as a single (data) segment, and are subject to some wasted space due to breakage.

Other signals may be raised when Newing modules; these signals indicate that the Bcd being loaded is invalid, versions of interfaces don’t match, or code files cannot be found or were compiled in non-Alto mode. In addition, when a module is started, the signal StartFault may be raised (see the section on Traps for more information).

Code Manipulation

The following procedures enable the user to control code swapping.

MakeCodeResident: PROCEDURE [f: GlobalFrameHandle];

Swaps in the code for f as low as possible in memory by pushing unlocked read-only segments out of the way. It will first swap out the code if it is swapped in.

LockCode: PROCEDURE [link: UNSPECIFIED];

Swaps in and locks the code segment associated with link (which may be either a PROCEDURE, POINTER TO FRAME or PROGRAM). The procedure GlobalFrame is used to find the global frame of link (and may raise the signals InvalidGlobalFrame and UnboundProcedure).

Warning: calling LockCode on a global frame that has not been started will disable start traps on that module.

UnlockCode: PROCEDURE [link: UNSPECIFIED];

Unlocks the code segment associated with link (which may be either a PROCEDURE, POINTER TO FRAME or PROGRAM). The procedure GlobalFrame is used to find the global frame of link (and may raise the signals InvalidGlobalFrame and UnboundProcedure).

SwapOutCode: PROCEDURE [f: GlobalFrameHandle];

Swaps out the code for f. If the code is locked, the ERROR SegmentDefs.SwapError is raised for the code segment associated with f.

Fine point: when a frame’s code is swapped out, all the global frames that have the same code segment will be updated to reflect the fact that the code is swapped out. These other frames either have their code segments packed with that frame or they are copies of that frame. Code may be swapped out by clients calling SwapOutCode or by the system.

SwapInCode: PROCEDURE [f: GlobalFrameHandle];

Swaps in and locks the code for f.

Warning: calling SwapInCode on a global frame that has not been started will disable start traps on that module.

Miscellaneous Operations

The following procedures are useful for debugging and determining what has been loaded.

GetCaller: PROCEDURE RETURNS [PROGRAM];

Returns the module containing its caller’s caller.

IsBound: PROCEDURE [link: UNSPECIFIED] RETURNS [BOOLEAN];

In cases where configurations are conditionally loaded, IsBound can be used to determine the presence of a module or procedure. The UNSPECIFIED argument should be an imported procedure or program, or pointer to an imported variable.