RTSymbols.mesa
Copyright © 1985 by Xerox Corporation. All rights reserved.
Rovner On July 22, 1983 5:36 pm
Russ Atkinson (RRA) February 11, 1985 12:17:04 pm PST
An interface to operations that acquire and release SymbolTableBases and SymbolTableHandles.
Bifurcation for symbol table bootstrapping occurs below this (and the RTSymbolOps) level of
abstraction.
DIRECTORY
BcdDefs USING[SGIndex, VersionStamp, NullVersion, BcdBase],
PrincOps USING[GlobalFrameHandle],
Rope USING[ROPE],
SafeStorage USING[Type],
RTSymbolDefs USING[SymbolTableHandle, SymbolTableBase, SymbolModuleIndex, SymbolIndex];
RTSymbols: DEFINITIONS = BEGIN OPEN BcdDefs, PrincOps, Rope, RTSymbolDefs, SafeStorage;
STB's
Note that all operations that attempt to acquire symbols may result in ERROR AMTypes.Error[noSymbols] if the necessary file cannot be found (or is otherwise not available).
AcquireSTB: PROC [sth: SymbolTableHandle] RETURNS [SymbolTableBase];
Given a SymbolTableHandle, instantiates and returns the indicated SymbolTableBase.
ReleaseSTB: PROC [stb: SymbolTableBase];
... releases a SymbolTableHandle.
BEWARE. The client is responsible for matching each AcquireSTB with exactly one ReleaseSTB. In particular, one should be very careful to catch UNWIND in appropriate places and ReleaseSTB. All the awfulness of dangling reference problems obtain at this level in the system.
OuterFromSTH: PROC [sth: SymbolTableHandle, inner: PROC [stb: SymbolTableBase] ];
Provided as a convenience for clients who want to know that they have been adequately protected against failure to release a symbol table. It is (roughly) equivalent to the following code:
stb: SymbolTableBase ← AcquireSTB[sth];
inner[stb ! ENABLE UNWIND => ReleaseSTB[stb] ];
ReleaseSTB[stb];
AcquireSTBFromGFH: PROC [gfh: GlobalFrameHandle] RETURNS [SymbolTableBase];
... returns a SymbolTableBase for a given global frame. As usual, the SymbolTableBase must be returned via ReleaseSTB.
OuterFromGFH: PROC [gfh: GlobalFrameHandle, inner: PROC [stb: SymbolTableBase] ];
Provided as a convenience for clients who want to know that they have been adequately protected against failure to release a symbol table. It is (roughly) equivalent to the following code:
stb: SymbolTableBase ← AcquireSTBFromGFH[gfh];
inner[stb ! ENABLE UNWIND => ReleaseSTB[stb] ];
ReleaseSTB[stb];
AcquireSTBFromMDI: PROC [stb: SymbolTableBase, mdi: SymbolModuleIndex] RETURNS [SymbolTableBase];
... returns a SymbolTableBase for a given SymbolModuleIndex. As usual, the SymbolTableBase must be returned via ReleaseSTB.
OuterFromMDI: PROC [stb: SymbolTableBase, mdi: SymbolModuleIndex, inner: PROC [base: SymbolTableBase]];
Provided as a convenience for clients who want to know that they have been adequately protected against failure to release a symbol table. It is (roughly) equivalent to the following code:
stbN: SymbolTableBase ← AcquireSTBFromMDI[stb, mdi];
inner[stb ! ENABLE UNWIND => ReleaseSTB[stbN] ];
ReleaseSTB[stb];
AcquireSTBFromSGI: PROC [bcd: BcdBase, sgi: SGIndex] RETURNS [SymbolTableBase];
... returns a SymbolTableBase for a given bcd and segment. As usual, the SymbolTableBase must be returned via ReleaseSTB.
OuterFromSGI: PROC [bcd: BcdBase, sgi: SGIndex, inner: PROC [base: SymbolTableBase]];
Provided as a convenience for clients who want to know that they have been adequately protected against failure to release a symbol table. It is (roughly) equivalent to the following code:
stb: SymbolTableBase ← AcquireSTBFromSGI[bcd, sgi];
inner[stb ! ENABLE UNWIND => ReleaseSTB[stb] ];
ReleaseSTB[stb];
STH's
NewSymbolHandle: PROC [fileName: ROPE, base: CARDINAL, pages: CARDINAL, version: VersionStamp ← NullVersion] RETURNS [SymbolTableHandle];
If version # AnyVersion, NewSymbolHandle may return a SymbolTableHandle that identifies a different file and span.
GetSTHForModule: PROC [stamp: VersionStamp, fileName: ROPE, moduleName: ROPE] RETURNS [SymbolTableHandle];
... acquires the STH given a version stamp and optional file names. If stamp = NullVersion, then the file and module names are not optional, and any version will be accepted. If stamp # NullVersion, then only that version will be accepted. The file and module names are optional if the module is found in the already present symbols, or if the version map(s) yield a result.
BaseToHandle: PROC [stb: SymbolTableBase] RETURNS [SymbolTableHandle];
... returns the SymbolTableHandle that denotes the given SymbolTableBase.
STPages: PROC [sth: SymbolTableHandle] RETURNS [CARDINAL];
... returns the number of pages in the specified symbol table
Types
GetTypeSymbols: PROC [type: Type] RETURNS [stb: SymbolTableBase, sei: SymbolIndex];
GetOriginalTypeSymbols: PROC [type: Type] RETURNS [stb: SymbolTableBase, sei: SymbolIndex];
END.