edu.princeton.toy.lang
Class TVirtualMachine

java.lang.Object
  extended by edu.princeton.toy.lang.TVirtualMachine

public class TVirtualMachine
extends 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
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
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
TVirtualMachine()
          Constructs a completely blank TVirtualMachine.
 
Method Summary
 void addChangeListener(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.
 String getCoreDump()
          Returns a core dump of the toy machine.
 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 sector.
 void getMem(TWord[] array)
          Copies all of the virtual machine's memory onto the given TWord array.
 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.
 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(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 sector.
 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 Throwable
Override the finalize() method to also interrupt the Runner.

Overrides:
finalize in class Object
Throws:
Throwable

addChangeListener

public void addChangeListener(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(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.


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 sector.

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 sector.

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 sector. 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 String getStderr()
Returns the standard error stream.

Returns:
the standard error stream.

getMemDump

public 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 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 String getCoreDump(boolean distinguishUninitialized)
Returns a core dump of the toy machine.

Parameters:
distinguishUninitialized - If true, uninitialized memory sectors 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()