INTERFACE JunoRT;

The Juno machine maintains an internal Boolean variable that is set by some instructions and tested by others. It also maintains a run-time stack, which contains both procedure frames and Juno values.

All procedures in this interface are un-monitored.

IMPORT JunoRTError, JunoValue;
IMPORT Atom;

TYPE
  ByteCode = BITS 8 FOR [0..255];
  ByteStream = REF ARRAY OF ByteCode;

  ExternalCode = BRANDED "JunoRT.ExternalCode" OBJECT METHODS
    invoke(): BOOLEAN
  END;

VAR
  value_tbl: REF ARRAY OF JunoValue.T;
  code_tbl:  REF ARRAY OF ByteStream;
  ext_code_tbl: REF ARRAY OF ExternalCode;

Use only the three procedures below to manipulate the value and code tables.

PROCEDURE GetValueIndex(val: JunoValue.T): CARDINAL;

Return the value index previously allocated to val, or allocate and return a value index i for val (initializing value_tbl[i] to val) if one has not been allocated for it previously. Indices returned by this procedure reference read-only values.

PROCEDURE GetVarIndex(md, nm: Atom.T): CARDINAL;

Return the value index previously allocated to the qualified ID md . nm, or allocate and return a value index for that QID if one has not been allocated for it previously.

TYPE
  ProcAttr = RECORD modName, name: Atom.T; sig: Sig END;
  Sig = RECORD outs, inouts, ins: CARDINAL END;

PROCEDURE GetCodeIndex(READONLY pa: ProcAttr): CARDINAL;

Return the code index previously allocated to the internal procedure with the name in pa, or allocate and return an index for that procedure if one has not been allocated for it previously. Requires that pa be valid.

PROCEDURE GetExtCodeIndex(READONLY pa: ProcAttr): CARDINAL;

Return the code index previously allocated to the external procedure with the name in pa, or allocate and return an index for that procedure if one has not been allocated for it previously. Requires that pa be valid.

PROCEDURE GetProcAttr(s: CARDINAL): ProcAttr;

Return the attributes of the internal procedure in slot s.

PROCEDURE GetExtProcAttr(s: CARDINAL): ProcAttr;

Return the attributes of the external procedure in slot s.

TYPE
  PC = RECORD proc: CARDINAL; offset: CARDINAL END;

Frame <: FramePublic;
  FramePublic = OBJECT METHODS
    down(): Frame;			 (* was "prev" *)
    up(): Frame;			 (* was "next" *)
    getLocal(i: INTEGER): JunoValue.T;
    setLocal(i: INTEGER; v: JunoValue.T);
    pc(): PC;
    setPC(pc: PC);
  END;

The stack grows from the initial base frame upwards. Hence, the frame for the currently running procedure is the topmost frame. In the machine's initial state, the base and topmost frames are the same.

The down and up methods report the adjoining Frame's in the stack. The base frame always has f.pc() = PC{0,0} and f.down() = NIL. The topmost frame always has f.up() = NIL.

Local arguments in a frame (both procedure arguments and temporaries) can be accessed with the getLocal and setLocal methods. See the description in the JunoByteCode interface for how local variables are indexed. It is an unchecked run-time error to supply an index which is outside the valid range for the procedure to which the frame corresponds. The value returned by getLocal for unitialized variables may be (Modula-3) NIL.

The pc method reports the frame's program counter. The setPC method sets the frame's program counter.

Various procedures cause Frame objects to become invalid. Once a frame becomes invalid, invoking any operation on it is an unchecked run-time error.

PROCEDURE BaseFrame(): Frame;

Returns the initial base frame.

PROCEDURE TopFrame(): Frame;

Returns the topmost frame.

PROCEDURE PushFrame(new_pc: PC; size: CARDINAL);

Creates a new frame f with size arguments such that f.down() is the current topmost frame, and f.pc() = pc. Initially, f.getArgument(i) = NIL for each i in the range [0..size-1]. If necessary, this procedure automatically enlarges the stack to hold the size arguments and the new frame pointer. This procedure sets pc to new_pc.

PROCEDURE PopFrame();

Invalidates the current topmost frame; the frame below the the old topmost frame becomes the topmost frame. It is a checked run-time error to invoke this procedure when the machine is in the initial state.

PROCEDURE ResetMachine();

Resets the Juno machine to its initial state, in which the base and top frames are the same.

PROCEDURE Save();

Saves the current machine state, including the entire stack. Doesn't currently save the value table, though maybe it should.

PROCEDURE Restore();

Restores the state to the one that was last saved by a call to Save(). It is a checked run-time error if no state has been previously saved.

PROCEDURE GetStackSize(): CARDINAL;

Reports the current size of the run-time stack.

PROCEDURE EnlargeStack();

Doubles the size of the run-time stack, while preserving all aspects of the machine state.

TYPE TrapCode = {NormalHalt, BreakPoint, Error, Interrupt, StackOverflow};

TYPE ExecRes = RECORD
  trapCode: TrapCode;
  trapLoc: PC;
  extSlot: CARDINAL;
  errorCode: JunoRTError.Code
END;

PROCEDURE TrapMessage(READONLY execRes: ExecRes): TEXT;

Return a descriptive error message for the execution result execRes.

PROCEDURE Interrupt();

Halt the currently running program at a convenient location with a TrapCode.Interrupt, and then return. This is a no-op if the machine is not currently running.

PROCEDURE Exec(): ExecRes;

Executes any code at the current pc of the bottom stack frame until a trap is encountered, and returns the execution result. All existing Frame objects become invalid once this procedure is invoked.

PROCEDURE ExecFromSlot(slot: CARDINAL; reset := TRUE): ExecRes;

Execute the code in the given code_tbl slot. If reset = TRUE, then call ResetMachine before executing the specified code.

END JunoRT.