TVirtualMachine (Visual X-TOY)

java.lang.Object
- edu.princeton.toy.lang.TVirtualMachine

```
public class TVirtualMachine
extends java.lang.Object
```
TVirtualMachine is an object that encapsulates the concept of the Toy Machine. This includes a program counter, set of registers, memory array, and a set of I/O buffers.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`TVirtualMachine.ExecutionController` ExecutionController is an interface that classes which wish to recieve notifications of a ToyVirtualMachine's termination should implement.
`protected class`	`TVirtualMachine.Runner` Runner is a simple implementation of Runnable for the Thread stated by the run() method of the TVM.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`MEM_COUNT` The size of the memory array.
`static TWord`	`PC_START` The address on which the Virtual Machine begins execution.
`static short`	`PC_START_VALUE` The address on which the Virtual Machine begins execution.
`static int`	`REGISTER_COUNT` The number of registers.

Constructor Summary

Constructors
Constructor and Description

TVirtualMachine()
Constructs a completely blank TVirtualMachine.

Constructors
Constructor and Description
`TVirtualMachine()` Constructs a completely blank TVirtualMachine.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addChangeListener(javax.swing.event.ChangeListener listener)` Adds a listener to monitor changes in the state of this machine.
`void`	`finalize()` Override the finalize() method to also interrupt the Runner.
`protected void`	`fireStateChanged()` Fires a state changed event to all the listeners.
`TWordBuffer`	`getConsumedStdin()` Returns the TWordBuffer containing all of the words which have been read already.
`TWordBuffer`	`getConsumedStdin(TWordBuffer buffer)` Copies all of the words which have been read already to the provided TWordBuffer.
`java.lang.String`	`getCoreDump()` Returns a core dump of the toy machine.
`java.lang.String`	`getCoreDump(boolean distinguishUninitialized)` Returns a core dump of the toy machine.
`TWord`	`getCurrentInstruction()` Returns the current instruction.
`boolean`	`getDistinguishUninitialized()` A convenience method for determining wheter or not uninitialied values should be distinguished from a simple zero.
`TExceptionHandler`	`getExceptionHandler()` Returns the exception handler.
`TWord`	`getMem(int index)` Returns the value at the requested memory memory.
`void`	`getMem(TWord[] array)` Copies all of the virtual machine's memory onto the given TWord array.
`java.lang.String`	`getMemDump()` Returns a memory dump of the toy machine, which could be parsed by Visual X-TOY as another program.
`TWord`	`getProgramCtr()` Returns the program counter.
`TWord`	`getRegister(int index)` Get the value of a particular register.
`java.lang.String`	`getStderr()` Returns the standard error stream.
`TWordBuffer`	`getStdout()` Returns the TWordBuffer containing all of the words which have been outputted by the virtual machine.
`TWordBuffer`	`getStdout(TWordBuffer buffer)` Copies all of the words which have been outputted by the virtual machine to the provided TWordBuffer.
`TWordBuffer`	`getUnconsumedStdin()` Returns the TWordBuffer containing all of the words which have not been read yet.
`TWordBuffer`	`getUnconsumedStdin(TWordBuffer buffer)` Copies all of the words which have not been read yet to the provided TWordBuffer.
`boolean`	`hasEncounteredError()` Returns true iff an error has been encountered.
`void`	`initMem(TWord[] words)` Initializes all of memory with an array of size exactly MEM_COUNT containing no null values.
`void`	`interrupt()` Will cause the runner (started by the run method) to stop.
`boolean`	`isDone()` Returns wheter or not the GUI should continue stepping.
`boolean`	`isRunning()` Returns wheter or not the runner (started by the run method) is running.
`boolean`	`needsInput()` Returns wheter or not the GUI should prompt the user for input.
`void`	`removeChangeListener(javax.swing.event.ChangeListener listener)` Removes a listener from this machine.
`void`	`reset()` Wipes out the memory and registers, resets the programCtr to PC_START, and flushes the streams.
`boolean`	`run(TVirtualMachine.ExecutionController controller)` Executes the command which programCtr points to and increments programCtr if necessary n times, dispatching ChangeEvents to all the listeners afterwards.
`void`	`setExceptionHandler(TExceptionHandler exceptionHandler)` Sets the exception handler.
`void`	`setMem(int index, TWord word)` Sets the value of the specified memory memory.
`void`	`setProgramCtr(TWord programCtr)` Change the programCtr.
`void`	`setRegister(int index, TWord word)` Sets the value of a particular register.
`void`	`setStdin(TWordBuffer unconsumedStdin)` Clears the consumedStdin and sets unconsumedStdin to contain the values provided.
`void`	`setStdin(TWordBuffer consumedStdin, TWordBuffer unconsumedStdin)` Sets the consumedStdin and unconsumedStdin to contain the values provided.
`int`	`step()` Executes the command which programCtr points to and increments programCtr if necessary one time, dispatching ChangeEvents to all the listeners afterwards.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - MEM_COUNT
```
public static final int MEM_COUNT
```
    The size of the memory array.
    
    See Also:
    Constant Field Values
  - REGISTER_COUNT
```
public static final int REGISTER_COUNT
```
    The number of registers.
    
    See Also:
    Constant Field Values
  - PC_START
```
public static final TWord PC_START
```
    The address on which the Virtual Machine begins execution.
  - PC_START_VALUE
```
public static final short PC_START_VALUE
```
    The address on which the Virtual Machine begins execution.
- Constructor Detail
  - TVirtualMachine
```
public TVirtualMachine()
```
    Constructs a completely blank TVirtualMachine.
- Method Detail
  - finalize
```
public void finalize()
              throws java.lang.Throwable
```
    Override the finalize() method to also interrupt the Runner.
    
    Overrides:
    
    finalize in class java.lang.Object
    
    Throws:
    
    java.lang.Throwable
  - addChangeListener
```
public void addChangeListener(javax.swing.event.ChangeListener listener)
```
    Adds a listener to monitor changes in the state of this machine.
    
    Parameters:
    listener - The listener to add to this virtualMachine. A null value will cause a NullPointerException.
  - removeChangeListener
```
public void removeChangeListener(javax.swing.event.ChangeListener listener)
```
    Removes a listener from this machine. Nothing will happen if no match was found.
    
    Parameters:
    listener - The listener to remove from this virtualMachine. A null value will cause a NullPointerException.
  - hasEncounteredError
```
public boolean hasEncounteredError()
```
    Returns true iff an error has been encountered.
    
    Returns:
    True iff an exception has been raised but not ignored.
  - isDone
```
public boolean isDone()
```
    Returns wheter or not the GUI should continue stepping.
    
    Returns:
    True iff the Virtual Machine has encountered an error or has reached a halt statement.
  - needsInput
```
public boolean needsInput()
```
    Returns wheter or not the GUI should prompt the user for input.
    
    Returns:
    True iff the stdin buffer is empty and the VM has an executed a command to read from stdin.
  - getDistinguishUninitialized
```
public boolean getDistinguishUninitialized()
```
    A convenience method for determining wheter or not uninitialied values should be distinguished from a simple zero. If any of the uninitialized class of exceptions is ignored by the exception handler, then this method will return false. Otherwise, true will be returned.
    
    Returns:
    True iff any of the uninitialized class of exceptions is ignored by the exception handler.
  - getExceptionHandler
```
public TExceptionHandler getExceptionHandler()
```
    Returns the exception handler.
    
    Returns:
    the exception handler.
  - setExceptionHandler
```
public void setExceptionHandler(TExceptionHandler exceptionHandler)
```
    Sets the exception handler.
    
    Parameters:
    exceptionHandler - The exception handler. A null value will result in a NullPointerException.
  - getProgramCtr
```
public TWord getProgramCtr()
```
    Returns the program counter.
    
    Returns:
    the program counter.
  - setProgramCtr
```
public void setProgramCtr(TWord programCtr)
```
    Change the programCtr.
    
    Parameters:
    programCtr - The new value of the programCtr. A null value will result in a NullPointerException.
  - getRegister
```
public TWord getRegister(int index)
```
    Get the value of a particular register.
    
    Parameters:
    index - The index of the requested register. An invalid value will result in an ArrayIndexOutOfBoundsException.
    
    Returns:
    The value of the requested register.
  - setRegister
```
public void setRegister(int index,
               TWord word)
```
    Sets the value of a particular register.
    
    Parameters:
    index - The index of the register to be changed. An invalid value will result in an ArrayIndexOutOfBoundsException.
    word - The new value of the register. A null value will result in a NullPointerException.
  - getCurrentInstruction
```
public TWord getCurrentInstruction()
```
    Returns the current instruction.
    
    Returns:
    Returns the current instruction. Null is returned if pc is out of bounds and if the exception handler does not ignore 'pc out of bounds' errors.
    See Also:
    getMem(int), getProgramCtr()
  - getMem
```
public void getMem(TWord[] array)
```
    Copies all of the virtual machine's memory onto the given TWord array.
    
    Parameters:
    array - The array on which to copy the virtual machine's memory. If the array is null, a NullPointerException will be thrown, if the array is too small, an ArrayIndexOutOfBoundsException will be thrown.
  - getMem
```
public TWord getMem(int index)
```
    Returns the value at the requested memory memory.
    
    Parameters:
    index - The address of the requested value. An invalid value will result in an ArrayIndexOutOfBoundsException.
    
    Returns:
    The value at the requested memory address.
  - setMem
```
public void setMem(int index,
          TWord word)
```
    Sets the value of the specified memory memory.
    
    Parameters:
    index - The address of the value to be changed. An invalid value will result in an ArrayIndexOutOfBoundsException.
    word - The new value of the memory memory. A null value will result in a NullPointerException.
  - initMem
```
public void initMem(TWord[] words)
```
    Initializes all of memory with an array of size exactly MEM_COUNT containing no null values.
    
    Parameters:
    words - The new contents of the memory array. A null value will result in a NullPointerException, and an incorrect length will result in an IllegalArgumentException.
  - getConsumedStdin
```
public TWordBuffer getConsumedStdin()
```
    Returns the TWordBuffer containing all of the words which have been read already. This is only a copy of the internal TWordBuffer.
    
    Returns:
    The TWordBuffer containing all of the words which have been read already.
  - getConsumedStdin
```
public TWordBuffer getConsumedStdin(TWordBuffer buffer)
```
    Copies all of the words which have been read already to the provided TWordBuffer.
    
    Parameters:
    buffer - The buffer to copy the data to. The buffer will be cleared before the copy.
    
    Returns:
    The same TWordBuffer that was passed as an argument.
  - getUnconsumedStdin
```
public TWordBuffer getUnconsumedStdin()
```
    Returns the TWordBuffer containing all of the words which have not been read yet. This is only a copy of the internal TWordBuffer.
    
    Returns:
    The TWordBuffer containing all of the words which have not been read yet.
  - getUnconsumedStdin
```
public TWordBuffer getUnconsumedStdin(TWordBuffer buffer)
```
    Copies all of the words which have not been read yet to the provided TWordBuffer.
    
    Parameters:
    buffer - The buffer to copy the data to. The buffer will be cleared before the copy.
    
    Returns:
    The same TWordBuffer that was passed as an argument.
  - setStdin
```
public void setStdin(TWordBuffer unconsumedStdin)
```
    Clears the consumedStdin and sets unconsumedStdin to contain the values provided. Note that the TWordBuffer provided will not be used as the internal TWordBuffer, nor will it be modified during the duplication process.
    
    Parameters:
    unconsumedStdin - The new values for the unconsumed stdin. A null implies that no changes should be made to the current value.
  - setStdin
```
public void setStdin(TWordBuffer consumedStdin,
            TWordBuffer unconsumedStdin)
```
    Sets the consumedStdin and unconsumedStdin to contain the values provided. Note that the TWordBuffers provided will not be used as the internal TWordBuffers, nor will they be modified during the duplication process.
    
    Parameters:
    consumedStdin - The new values for the consumed stdin. A null implies that no changes should be made to the current value.
    unconsumedStdin - The new values for the unconsumed stdin. A null implies that no changes should be made to the current value.
  - getStdout
```
public TWordBuffer getStdout()
```
    Returns the TWordBuffer containing all of the words which have been outputted by the virtual machine. This is only a copy of the internal TWordBuffer.
    
    Returns:
    The TWordBuffer containing all of the words which have not been read yet.
  - getStdout
```
public TWordBuffer getStdout(TWordBuffer buffer)
```
    Copies all of the words which have been outputted by the virtual machine to the provided TWordBuffer.
    
    Parameters:
    buffer - The buffer to copy the data to. The buffer will be cleared before the copy.
    
    Returns:
    The same TWordBuffer that was passed as an argument.
  - getStderr
```
public java.lang.String getStderr()
```
    Returns the standard error stream.
    
    Returns:
    the standard error stream.
  - getMemDump
```
public java.lang.String getMemDump()
```
    Returns a memory dump of the toy machine, which could be parsed by Visual X-TOY as another program.
    
    Returns:
    A memory dump of the toy machine.
  - getCoreDump
```
public java.lang.String getCoreDump()
```
    Returns a core dump of the toy machine. The virtual machine will used the exception handler to decide wheter or not to distinguish uninitialized values from a simple zero.
    
    Returns:
    getCoreDump(getDistinguishUninitialized()).
  - getCoreDump
```
public java.lang.String getCoreDump(boolean distinguishUninitialized)
```
    Returns a core dump of the toy machine.
    
    Parameters:
    distinguishUninitialized - If true, uninitialized memory memorys and registers will show ???? instead of 0000.
    
    Returns:
    A core dump of the toy machine.
  - reset
```
public void reset()
```
    Wipes out the memory and registers, resets the programCtr to PC_START, and flushes the streams.
  - fireStateChanged
```
protected void fireStateChanged()
```
    Fires a state changed event to all the listeners.
  - interrupt
```
public void interrupt()
```
    Will cause the runner (started by the run method) to stop.
    
    See Also:
    isRunning(), run(TVirtualMachine.ExecutionController)
  - isRunning
```
public boolean isRunning()
```
    Returns wheter or not the runner (started by the run method) is running.
    
    Returns:
    True iff the runner is running.
    See Also:
    interrupt(), run(TVirtualMachine.ExecutionController)
  - step
```
public int step()
```
    Executes the command which programCtr points to and increments programCtr if necessary one time, dispatching ChangeEvents to all the listeners afterwards.
    
    Returns:
    The number of times actually stepped. 0 will be returned if any of isDone(), needsInput(), or isRunning() is true, otherwise, 1 will be returned.
  - run
```
public boolean run(TVirtualMachine.ExecutionController controller)
```
    Executes the command which programCtr points to and increments programCtr if necessary n times, dispatching ChangeEvents to all the listeners afterwards. Note that a halt command, needsInputFlag, interrupt() call, or exception could all prematurely stop the stepping.
    
    Parameters:
    controller - The implementation of ExecutionController which will recieve notification of the completion of a batch of steps and control the size of each batch. A null value will result in a NullPointerException.
    
    Returns:
    True iff a runner was actually started. A runner will not be started if n is 0, or if any of isDone(), needsInput(), or isRunning() is true.
    See Also:
    interrupt(), isRunning()

Class TVirtualMachine

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MEM_COUNT

REGISTER_COUNT

PC_START

PC_START_VALUE

Constructor Detail

TVirtualMachine

Method Detail

finalize

addChangeListener

removeChangeListener

hasEncounteredError

isDone

needsInput

getDistinguishUninitialized

getExceptionHandler

setExceptionHandler

getProgramCtr

setProgramCtr

getRegister

setRegister

getCurrentInstruction

getMem

getMem

setMem

initMem

getConsumedStdin

getConsumedStdin

getUnconsumedStdin

getUnconsumedStdin

setStdin

setStdin

getStdout

getStdout

getStderr

getMemDump

getCoreDump

getCoreDump

reset

fireStateChanged

interrupt

isRunning

step

run