Runtime (API documentation of hlt.language packages)
Date: 2013-01-30

hlt.language.design.backend

## Class Runtime

- java.lang.Object
- - hlt.language.design.backend.Runtime

-     public class Runtime
      extends java.lang.Object

  This is the class defining a runtime object. Such an object serves as the common execution environment context shared by `Instruction`s being executed. It encapsulates a state of comptutation that is effected by each instruction as it is executed in its context.

  A `Runtime` object consists of attributes and structures that together define a state of computation, and methods that are used by instructions to effect this state as they are executed. Thus, each instruction class defines an `execute(Runtime)` method that specifies its operational semantics as a state transformation of its given runtime context.

  Initiating execution of a `Runtime` object consists of setting its code array to a given instruction sequence, setting its instruction pointer `_ip` to its code's first instruction and repeatedly calling `execute(this)` on whatever instruction is currently at address `_ip` in the current code array. The final state is reached when a flag indicating that it is so is set to `true`. Each instruction is responsible for appropriately setting the next state according to its semantics, including saving and restoring states, and (re)setting the code array and the various runtime registers pointing into the state's structures.

  Runtime states encapsulated by objects in this class are essentially those of a stack automaton, specifically conceived to support the computations of a higher-order functional language with lexical closures - i.e., a λ-calculus machine. As such it may viewed as an optimized variant of Peter Landin's SECD machine - in the same spirit as Luca Cardelli's Functional Abstract Machine (FAM), although our design is quite different from Cardelli's in its structure and operations. It supports many features beyond basic λ-calculus - e.g., in-place assignments (both stack-based and heap-based), automatic boxing/unboxing for polymorphic functions, objects, automatic currying, to name a few...

  Because this is a Java implementation, in order to avoid the space and performance overhead of being confined to boxed values for primitive type computations, three concurrent sets of structures are maintained: in addition to those needed for boxed (Java object) values, two extra ones are used to support unboxed integer and floating-point values, respectively. The runtime operations performed by instructions on a `Runtime` object are guaranteed to be type-safe in that each state is always such as it must be expected for the correct accessing and setting of values. Such a guarantee must be (and is!) provided by the `TypeChecker` and the `Sanitizer`, which ascertain all the conditions that must be met prior to having a `Compiler` proceed to generating instructions which will safely act on the appropriate stacks and environments of the correct sort (integer, floating-point, or object).

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static RuntimeInt` | `BOXED_FALSE` A constant that denotes the boxed boolean `false` at runtime.
    `static RuntimeInt` | `BOXED_TRUE` A constant that denotes the boxed boolean `true` at runtime.
    `static RuntimeInt` | `BOXED_VOID` A constant that denotes the boxed `void` value at runtime.
    `static int` | `FALSE` A constant that denotes the unboxed boolean `false` at runtime.
    `static int` | `TRUE` A constant that denotes the unboxed boolean `true` at runtime.
    `static int` | `VOID` A constant that denotes the unboxed `void` value at runtime.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Runtime()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `booleanResult()` Returns the value of the latest boolean pushed on the result stack.
    `static double[]` | `copy(double[] source)` Returns a copy of the specified array of doubles.
    `static int[]` | `copy(int[] source)` Returns a copy of the specified array of ints.
    `static java.lang.Object[]` | `copy(java.lang.Object[] source)` Returns a deep copy of the specified array of objects; i.e., objects that are arrays or `RuntimeMap`s are also copied recursively.
    `int[]` | `copyIntEnv(int size)` Copies the latest `size` int values from the environment stack into an array, and returns the array.
    `java.lang.Object[]` | `copyObjectEnv(int size)` Copies the latest `size` objects from the environment stack into an array, and returns the array.
    `double[]` | `copyRealEnv(int size)` Copies the latest `size` double values from the environment stack into an array, and returns the array.
    `DisplayDeviceManager` | `displayDeviceManager()` Returns this runtime's display device manager.
    `DisplayFormManager` | `displayFormManager()` Returns this runtime's display form manager.
    `DisplayManager` | `displayManager()` Returns this runtime's display manager.
    `void` | `enterExitableScope()` Saves the current state and pushes it onto the exitable state stack.
    `void` | `enterExitableScope(int intArity, int realArity, int objectArity)` Saves the state obtained after the result stacks have been popped as many arguments as the specified arities and pushes it onto the exitable state stack.
    `DisplayDeviceManager` | `getDisplayDeviceManager()` Returns this runtime's display device manager.
    `DisplayFormManager` | `getDisplayFormManager()` Returns this runtime's display form manager.
    `DisplayManager` | `getDisplayManager()` Returns this runtime's display manager.
    `int` | `getIntEnv(int n)` Returns the int value at offset `n` in the environment stack.
    `java.lang.Object` | `getObjectEnv(int n)` Returns the object at offset `n` in the environment stack.
    `double` | `getRealEnv(int n)` Returns the double value at offset `n` in the environment stack.
    `void` | `incIP()` Increments the instruction pointer (i.e., sets it to point to the next instruction in the code array).
    `void` | `initialize(Instruction[] code)` Resets this runtime and sets the code array to the specified one.
    `int` | `intResult()` Returns the value of the latest integer pushed on the result stack.
    `int` | `ip()` Returns the value of the current instruction pointer.
    `static boolean` | `isTracing()` Returns the tracing flag.
    `void` | `leaveExitableScope()` Restores the state that was saved when the latest exitable closure was applied.
    `static RuntimeInt` | `newInt(int value)` This returns a boxed integer with the specified int value; values `0` and `1` are boxed into unique canonical objects since they are frequently used.
    `static RuntimeReal` | `newReal(double value)` This returns a boxed real number with the specified double value; the value `0.0` is boxed into a unique canonical object it is frequently used.
    `java.lang.Object` | `objectResult()` Returns the value of the latest object pushed on the result stack.
    `boolean` | `popBoolean()` Removes and returns the value of the latest boolean pushed on the result stack.
    `void` | `popCall()` If the call stack is empty, this sets the termination flag to `true`; otherwise, pops a call state and restores from it the code array and the next instruction pointer.
    `char` | `popChar()` Returns the char corresponding to the Unicode numeric value popped from the result stack.
    `hlt.language.design.backend.Runtime.State` | `popExitableState()` Pops and returns the latest exitable `State` in the save stack that encloses this runtime's current state of computation.
    `int` | `popInt()` Removes and returns the value of the latest integer pushed on the result stack.
    `int[]` | `popIntArray()` Removes the latest object pushed on the result stack, which must be an array or an `IntMap`, and returns the array (i.e., if it's a map, extracts its array).
    `int[]` | `popIntArray(java.lang.Object infoIfNull)` If the latest object pushed on the result stack is `null`, this throws a `NullValueException` with the specified object as argument; otherwise, this works as `popIntArray()`.
    `java.lang.Object` | `popObject()` Removes and returns the value of the latest object pushed on the result stack.
    `java.lang.Object` | `popObject(java.lang.Object infoIfNull)` Removes and returns the value of the latest object pushed on the result stack if this object is not `null`.
    `java.lang.Object[]` | `popObjectArray()` Removes the latest object pushed on the result stack, which must be an array or an `ObjectMap`, and returns the array (i.e., if it's a map, extracts its array).
    `java.lang.Object[]` | `popObjectArray(java.lang.Object infoIfNull)` If the latest object pushed on the result stack is `null`, this throws a `NullValueException` with the specified object as argument; otherwise, this works as `popObjectArray()`.
    `double` | `popReal()` Removes and returns the value of the latest floating-point number pushed on the result stack.
    `double[]` | `popRealArray()` Removes the latest object pushed on the result stack, which must be an array or a `RealMap`, and returns the array (i.e., if it's a map, extracts its array).
    `double[]` | `popRealArray(java.lang.Object infoIfNull)` If the latest object pushed on the result stack is `null`, this throws a `NullValueException` with the specified object as argument; otherwise, this works as `popRealArray()`.
    `void` | `pushBoolean(boolean x)` Pushes the specified boolean on the result stack.
    `void` | `pushCall(DefinedEntry entry)` If the specified `DefinedEntry` is safe (i.e., it and all its calls are fully defined), this pushes it along with this runtime's current code array and next instruction pointer into the call stack, and sets this runtime's code array to that of the specified entry's and reset the instruction pointer to 0.
    `void` | `pushChar(char c)` Pushes the Unicode numeric value of the character as a nonnegative integer on the result stack.
    `void` | `pushExitableState(hlt.language.design.backend.Runtime.State state)` Pushes the specified state onto the exitable state stack.
    `void` | `pushInt(int x)` Pushes the specified integer on the result stack.
    `void` | `pushIntEnv(int x)` Pushes the specified int value on the environment stack.
    `void` | `pushIntEnvArray(int[] frame)` Pushes all the elements of the specified int array on the environment stack.
    `void` | `pushObject(java.lang.Object x)` Pushes the specified object on the result stack.
    `void` | `pushObjectEnv(java.lang.Object x)` Pushes the specified object on the environment stack.
    `void` | `pushObjectEnvArray(java.lang.Object[] frame)` Pushes all the elements of the specified object array on the environment stack.
    `void` | `pushReal(double x)` Pushes the specified double on the result stack.
    `void` | `pushRealEnv(double x)` Pushes the specified double value on the environment stack.
    `void` | `pushRealEnvArray(double[] frame)` Pushes all the elements of the specified double array on the environment stack.
    `double` | `realResult()` Returns the value of the latest floating-point number pushed on the result stack.
    `Runtime` | `reset()` Resets this runtime to a virginal state and returns this.
    `void` | `resetIP()` Resets the value of the current instruction pointer to 0, and unsets the termination flag.
    `void` | `restoreState()` Restores the latest state of computation that was saved in the save stack into this runtime.
    `void` | `restoreState(hlt.language.design.backend.Runtime.State s)` Restores the specified state of computation into this runtime.
    `byte` | `resultSort()` Returns the runtime sort of the latest value pushed on the result stack.
    `void` | `run()` Initiates execution of this runtime's code and proceeds as long as the termination flag is not set.
    `void` | `run(Instruction[] code)` Resets this runtime, sets the code array to the specified one, and initiates execution of this runtime's code, which proceeds as long as the termination flag is not set.
    `void` | `runBody(Block block)` Initiates execution of the specified block's body, and proceeds as long as the current instruction is not a return instruction.
    `hlt.language.design.backend.Runtime.State` | `saveState()` Saves this runtime's current state of computation onto the save stack and returns it.
    `hlt.language.design.backend.Runtime.State` | `saveState(int intArity, int realArity, int objectArity)` Saves this runtime's state of computation obtained after the result stacks have been popped as many arguments as the specified arities.
    `void` | `setCode(Instruction[] code)` Sets the code array to the specified one.
    `Runtime` | `setDisplayDeviceManager(DisplayDeviceManager displayDeviceManager)` Sets this runtime's display Device manager to the specified one, and returns this runtime.
    `Runtime` | `setDisplayFormManager(DisplayFormManager displayFormManager)` Sets this runtime's display Form manager to the specified one, and returns this runtime.
    `Runtime` | `setDisplayManager(DisplayManager displayManager)` Sets this runtime's display manager to the specified one, and returns this runtime.
    `void` | `setIntEnv(int n)` Sets the int environment stack slot at offset `n` to the latest int value that was pushed on the int result stack.
    `void` | `setIntSort()` Set the runtime sort of the latest value pushed on the result stack to be that of an int.
    `void` | `setIntValue(int n)` Sets the topmost int environment stack slot to the specified int value.
    `void` | `setIP(int ip)` Sets the value of the current instruction pointer to the specified one.
    `void` | `setObjectEnv(int n)` Sets the object environment stack slot at offset `n` to the latest object that was pushed on the object result stack.
    `void` | `setObjectSort()` Set the runtime sort of the latest value pushed on the result stack to be that of an object.
    `void` | `setObjectValue(java.lang.Object o)` Sets the topmost object environment stack slot to the spwcified object value.
    `void` | `setRealEnv(int n)` Sets the double environment stack slot at offset `n` to the latest double value that was pushed on the double result stack.
    `void` | `setRealSort()` Set the runtime sort of the latest value pushed on the result stack to be that of a real.
    `void` | `setRealValue(double x)` Sets the topmost real environment stack slot to the specified double value.
    `void` | `setValue(DefinedEntry entry)` Modifies the code array of the specified `DefinedEntry` to one that pushes the latest value that was pushed on this runtime's appropriate result stack.
    `void` | `showState()`
    `void` | `stop()` Stops the execution of this runtime.
    `static void` | `toggleTrace()` Toggles the tracing flag.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### FALSE

          public static final int FALSE

      A constant that denotes the unboxed boolean `false` at runtime.
      See Also:
        Constant Field Values

    - #### TRUE

          public static final int TRUE

      A constant that denotes the unboxed boolean `true` at runtime.
      See Also:
        Constant Field Values

    - #### VOID

          public static final int VOID

      A constant that denotes the unboxed `void` value at runtime.
      See Also:
        Constant Field Values

    - #### BOXED_FALSE

          public static final RuntimeInt BOXED_FALSE

      A constant that denotes the boxed boolean `false` at runtime.

    - #### BOXED_TRUE

          public static final RuntimeInt BOXED_TRUE

      A constant that denotes the boxed boolean `true` at runtime.

    - #### BOXED_VOID

          public static final RuntimeInt BOXED_VOID

      A constant that denotes the boxed `void` value at runtime.

  - ### Constructor Detail

    - #### Runtime

          public Runtime()

  - ### Method Detail

    - #### displayManager

          public final DisplayManager displayManager()

      Returns this runtime's display manager.

    - #### getDisplayManager

          public final DisplayManager getDisplayManager()

      Returns this runtime's display manager.

    - #### setDisplayManager

          public final Runtime setDisplayManager(DisplayManager displayManager)

      Sets this runtime's display manager to the specified one, and returns this runtime.

    - #### displayDeviceManager

          public final DisplayDeviceManager displayDeviceManager()

      Returns this runtime's display device manager.

    - #### getDisplayDeviceManager

          public final DisplayDeviceManager getDisplayDeviceManager()

      Returns this runtime's display device manager.

    - #### setDisplayDeviceManager

          public final Runtime setDisplayDeviceManager(DisplayDeviceManager displayDeviceManager)

      Sets this runtime's display Device manager to the specified one, and returns this runtime.

    - #### displayFormManager

          public final DisplayFormManager displayFormManager()

      Returns this runtime's display form manager.

    - #### getDisplayFormManager

          public final DisplayFormManager getDisplayFormManager()

      Returns this runtime's display form manager.

    - #### setDisplayFormManager

          public final Runtime setDisplayFormManager(DisplayFormManager displayFormManager)

      Sets this runtime's display Form manager to the specified one, and returns this runtime.

    - #### setCode

          public final void setCode(Instruction[] code)

      Sets the code array to the specified one.

    - #### ip

          public final int ip()

      Returns the value of the current instruction pointer.

    - #### setIP

          public final void setIP(int ip)

      Sets the value of the current instruction pointer to the specified one.

    - #### resetIP

          public final void resetIP()

      Resets the value of the current instruction pointer to 0, and unsets the termination flag.

    - #### incIP

          public final void incIP()

      Increments the instruction pointer (i.e., sets it to point to the next instruction in the code array).

    - #### pushInt

          public final void pushInt(int x)

      Pushes the specified integer on the result stack.

    - #### pushReal

          public final void pushReal(double x)

      Pushes the specified double on the result stack.

    - #### pushObject

          public final void pushObject(java.lang.Object x)

      Pushes the specified object on the result stack.

    - #### pushBoolean

          public final void pushBoolean(boolean x)

      Pushes the specified boolean on the result stack.

    - #### popChar

          public final char popChar()

      Returns the char corresponding to the Unicode numeric value popped from the result stack. This assumes that the integer value is non-negative.

    - #### pushChar

          public final void pushChar(char c)

      Pushes the Unicode numeric value of the character as a nonnegative integer on the result stack.

    - #### resultSort

          public final byte resultSort()

      Returns the runtime sort of the latest value pushed on the result stack.

    - #### setIntSort

          public final void setIntSort()

      Set the runtime sort of the latest value pushed on the result stack to be that of an int. This is useful for maintaining consistency when an instruction acts on the top of the result stack without popping it.

    - #### setRealSort

          public final void setRealSort()

      Set the runtime sort of the latest value pushed on the result stack to be that of a real. This is useful for maintaining consistency when an instruction acts on the top of the result stack without popping it.

    - #### setObjectSort

          public final void setObjectSort()

      Set the runtime sort of the latest value pushed on the result stack to be that of an object. This is useful for maintaining consistency when an instruction acts on the top of the result stack without popping it.

    - #### intResult

          public final int intResult()

      Returns the value of the latest integer pushed on the result stack.

    - #### realResult

          public final double realResult()

      Returns the value of the latest floating-point number pushed on the result stack.

    - #### objectResult

          public final java.lang.Object objectResult()

      Returns the value of the latest object pushed on the result stack.

    - #### booleanResult

          public final boolean booleanResult()

      Returns the value of the latest boolean pushed on the result stack.

    - #### popInt

          public final int popInt()

      Removes and returns the value of the latest integer pushed on the result stack.

    - #### popReal

          public final double popReal()

      Removes and returns the value of the latest floating-point number pushed on the result stack.

    - #### popObject

          public final java.lang.Object popObject()

      Removes and returns the value of the latest object pushed on the result stack.

    - #### popObject

          public final java.lang.Object popObject(java.lang.Object infoIfNull)
                                           throws NullValueException

      Removes and returns the value of the latest object pushed on the result stack if this object is not `null`. Otherwise, throws a `NullValueException` with the specified object as argument.
      Throws:
        `NullValueException`

    - #### popBoolean

          public final boolean popBoolean()

      Removes and returns the value of the latest boolean pushed on the result stack.

    - #### popIntArray

          public int[] popIntArray()

      Removes the latest object pushed on the result stack, which must be an array or an `IntMap`, and returns the array (i.e., if it's a map, extracts its array).

    - #### popIntArray

          public int[] popIntArray(java.lang.Object infoIfNull)
                            throws NullValueException

      If the latest object pushed on the result stack is `null`, this throws a `NullValueException` with the specified object as argument; otherwise, this works as `popIntArray()`.
      Throws:
        `NullValueException`

    - #### popRealArray

          public double[] popRealArray()

      Removes the latest object pushed on the result stack, which must be an array or a `RealMap`, and returns the array (i.e., if it's a map, extracts its array).

    - #### popRealArray

          public double[] popRealArray(java.lang.Object infoIfNull)
                                throws NullValueException

      If the latest object pushed on the result stack is `null`, this throws a `NullValueException` with the specified object as argument; otherwise, this works as `popRealArray()`.
      Throws:
        `NullValueException`

    - #### popObjectArray

          public java.lang.Object[] popObjectArray()

      Removes the latest object pushed on the result stack, which must be an array or an `ObjectMap`, and returns the array (i.e., if it's a map, extracts its array).

    - #### popObjectArray

          public java.lang.Object[] popObjectArray(java.lang.Object infoIfNull)
                                            throws NullValueException

      If the latest object pushed on the result stack is `null`, this throws a `NullValueException` with the specified object as argument; otherwise, this works as `popObjectArray()`.
      Throws:
        `NullValueException`

    - #### newInt

          public static final RuntimeInt newInt(int value)

      This returns a boxed integer with the specified int value; values `0` and `1` are boxed into unique canonical objects since they are frequently used.

    - #### newReal

          public static final RuntimeReal newReal(double value)

      This returns a boxed real number with the specified double value; the value `0.0` is boxed into a unique canonical object it is frequently used.

    - #### pushIntEnv

          public final void pushIntEnv(int x)

      Pushes the specified int value on the environment stack.

    - #### pushRealEnv

          public final void pushRealEnv(double x)

      Pushes the specified double value on the environment stack.

    - #### pushObjectEnv

          public final void pushObjectEnv(java.lang.Object x)

      Pushes the specified object on the environment stack.

    - #### pushIntEnvArray

          public final void pushIntEnvArray(int[] frame)

      Pushes all the elements of the specified int array on the environment stack.

    - #### pushRealEnvArray

          public final void pushRealEnvArray(double[] frame)

      Pushes all the elements of the specified double array on the environment stack.

    - #### pushObjectEnvArray

          public final void pushObjectEnvArray(java.lang.Object[] frame)

      Pushes all the elements of the specified object array on the environment stack.

    - #### copyIntEnv

          public final int[] copyIntEnv(int size)

      Copies the latest `size` int values from the environment stack into an array, and returns the array.

    - #### copyRealEnv

          public final double[] copyRealEnv(int size)

      Copies the latest `size` double values from the environment stack into an array, and returns the array.

    - #### copyObjectEnv

          public final java.lang.Object[] copyObjectEnv(int size)

      Copies the latest `size` objects from the environment stack into an array, and returns the array.

    - #### getIntEnv

          public final int getIntEnv(int n)

      Returns the int value at offset `n` in the environment stack.

    - #### getRealEnv

          public final double getRealEnv(int n)

      Returns the double value at offset `n` in the environment stack.

    - #### getObjectEnv

          public final java.lang.Object getObjectEnv(int n)

      Returns the object at offset `n` in the environment stack.

    - #### copy

          public static final int[] copy(int[] source)

      Returns a copy of the specified array of ints.

    - #### copy

          public static final double[] copy(double[] source)

      Returns a copy of the specified array of doubles.

    - #### copy

          public static final java.lang.Object[] copy(java.lang.Object[] source)

      Returns a deep copy of the specified array of objects; i.e., objects that are arrays or `RuntimeMap`s are also copied recursively.

    - #### setIntEnv

          public final void setIntEnv(int n)

      Sets the int environment stack slot at offset `n` to the latest int value that was pushed on the int result stack. The result stack is not popped.

    - #### setRealEnv

          public final void setRealEnv(int n)

      Sets the double environment stack slot at offset `n` to the latest double value that was pushed on the double result stack. The result stack is not popped.

    - #### setObjectEnv

          public final void setObjectEnv(int n)

      Sets the object environment stack slot at offset `n` to the latest object that was pushed on the object result stack. The result stack is not popped.

    - #### setIntValue

          public final void setIntValue(int n)

      Sets the topmost int environment stack slot to the specified int value.

    - #### setRealValue

          public final void setRealValue(double x)

      Sets the topmost real environment stack slot to the specified double value.

    - #### setObjectValue

          public final void setObjectValue(java.lang.Object o)

      Sets the topmost object environment stack slot to the spwcified object value.

    - #### pushExitableState

          public final void pushExitableState(hlt.language.design.backend.Runtime.State state)

      Pushes the specified state onto the exitable state stack. This stack is a substack of the save stack: it is threaded in-place from a global private register `_currentExitableState` which always points to the latest (if any, `null` otherwise) exitable `State` in the save stack that encloses this runtime's current state of computation. The exitable states in the stack are thus link-chained using the `setEnclosingExitableState(State)` and `getEnclosingExitableState()` methods.

    - #### popExitableState

          public final hlt.language.design.backend.Runtime.State popExitableState()

      Pops and returns the latest exitable `State` in the save stack that encloses this runtime's current state of computation. NB: Typechecking garantees that is is always non-`null`.

    - #### enterExitableScope

          public final void enterExitableScope()

      Saves the current state and pushes it onto the exitable state stack.

    - #### enterExitableScope

          public final void enterExitableScope(int intArity,
                                int realArity,
                                int objectArity)

      Saves the state obtained after the result stacks have been popped as many arguments as the specified arities and pushes it onto the exitable state stack.

    - #### leaveExitableScope

          public final void leaveExitableScope()

      Restores the state that was saved when the latest exitable closure was applied.

    - #### saveState

          public final hlt.language.design.backend.Runtime.State saveState()

      Saves this runtime's current state of computation onto the save stack and returns it. A state consists of the code array, the next instruction pointer, and the sizes of all the stacks.

    - #### saveState

          public final hlt.language.design.backend.Runtime.State saveState(int intArity,
                                                            int realArity,
                                                            int objectArity)

      Saves this runtime's state of computation obtained after the result stacks have been popped as many arguments as the specified arities.

    - #### restoreState

          public final void restoreState()

      Restores the latest state of computation that was saved in the save stack into this runtime.

    - #### restoreState

          public final void restoreState(hlt.language.design.backend.Runtime.State s)

      Restores the specified state of computation into this runtime.

    - #### pushCall

          public final void pushCall(DefinedEntry entry)
                              throws UnsafeCodeException

      If the specified `DefinedEntry` is safe (i.e., it and all its calls are fully defined), this pushes it along with this runtime's current code array and next instruction pointer into the call stack, and sets this runtime's code array to that of the specified entry's and reset the instruction pointer to 0. Otherwise, a `UnsafeCodeException` is thrown.
      Throws:
        `UnsafeCodeException`

    - #### popCall

          public final void popCall()

      If the call stack is empty, this sets the termination flag to `true`; otherwise, pops a call state and restores from it the code array and the next instruction pointer. If the entry from the popped state is to be set on evaluation, this will modify its code to return the latest value pushed on the appropriate result stack.

    - #### setValue

          public final void setValue(DefinedEntry entry)

      Modifies the code array of the specified `DefinedEntry` to one that pushes the latest value that was pushed on this runtime's appropriate result stack.

    - #### reset

          public final Runtime reset()

      Resets this runtime to a virginal state and returns this.

    - #### initialize

          public final void initialize(Instruction[] code)

      Resets this runtime and sets the code array to the specified one.

    - #### run

          public final void run(Instruction[] code)
                         throws java.lang.Exception

      Resets this runtime, sets the code array to the specified one, and initiates execution of this runtime's code, which proceeds as long as the termination flag is not set.
      Throws:
        `java.lang.Exception`

    - #### run

          public final void run()
                         throws java.lang.Exception

      Initiates execution of this runtime's code and proceeds as long as the termination flag is not set.
      Throws:
        `java.lang.Exception`

    - #### runBody

          public final void runBody(Block block)
                             throws java.lang.Exception

      Initiates execution of the specified block's body, and proceeds as long as the current instruction is not a return instruction.
      Throws:
        `java.lang.Exception`

    - #### stop

          public final void stop()

      Stops the execution of this runtime.

    - #### toggleTrace

          public static final void toggleTrace()

      Toggles the tracing flag.

    - #### isTracing

          public static final boolean isTracing()

      Returns the tracing flag.

    - #### showState

          public final void showState()