uk.ac.man.cs.rainbow.simulator
Class RASMThread

java.lang.Object
  |
  +--uk.ac.man.cs.rainbow.simulator.RainbowThread
        |
        +--uk.ac.man.cs.rainbow.simulator.RASMThread

public final class RASMThread

extends RainbowThread

Rainbow threads that are implemented by executing RASM instructions.

See Also:

RASMCode, RASM

Inner Class Summary

class	RASMThread.CallChain An encapsulation of the location of a thread.
static class	RASMThread.Characterisation The characterisation of a thread that doesn't specify its own.
static class	RASMThread.Exception Exceptions due to problems during the execution of a thread.
static class	RASMThread.InvokationException Thrown when an exception occurs in some externally referenced code.
static class	RASMThread.PopFailureException Thrown to indicate a problem during a pop operation.
static class	RASMThread.ReaderWriter For saving the activity on channels.
static class	RASMThread.RegPair A tuple of register and creation location.
static class	RASMThread.SavedRASMThreadState This thread's saved state.
static interface	RASMThread.TraceListener Implemented by classes that want to watch what a thread is doing.

Inner classes inherited from class uk.ac.man.cs.rainbow.simulator.RainbowThread

RainbowThread.IllegalChannelStateException, RainbowThread.IllegalThreadTerminationException, RainbowThread.SavedRainbowThreadState

Fields inherited from class uk.ac.man.cs.rainbow.simulator.RainbowThread

AFTER_CHOICE, BACKWARD, FORWARD, INITIALISE, scheduler

Constructor Summary

RASMThread(Scheduler scheduler, RASMCode code)
Create a new top-level thread.

Method Summary

void	addTraceListener(RASMThread.TraceListener tracer) Attach a trace listener to this object.
Channel	chanContext() Get the channel from the thread context or the stack.
Data	characterise() Characterise this thread and its children.
void	consolidateStack() Trim the space allocated to the stack.
boolean	endContext(boolean flag) Reset the context or repeat the instruction.
Data	execExtern(String externString) Pass a string to the client for external execution.
protected void	execute() Execute this thread according to where it is in its block of code.
void	fork(RASMCode.Label[] labels, Data[] args) Create a collection of child threads.
int	frameSize() How large is the current stack frame?
Object	getContext() Retrieve the context associated with the current instruction.
Data	getIdx(int idx) Read a value from an offset from the base of the current stack-frame.
boolean	haveContext() Is there any context associated with the current instruction?
void	keyRegister(Register reg, int key) Allow clients to inspect the given register.
void	labelChannel(Channel chan, String label) Put a client-determined label on a channel.
void	labelThread(Register reg, String label) Put a client-determined label on this thread.
void	loadState(SavedState saved) Reload a previously saved state.
void	markStaticBase() Mark the current point on the stack as having only unchanging values below it.
void	motionless() Cause the current instruction to be repeated.
Channel.Data	newChannel(String name) Create a new channel with the given name.
void	newFrame() Create a new stack frame.
Register.Data	newRegister(String name) Create a new register with the given name.
void	oldFrame() Return to an old stack frame.
Data	pop() Pop a single data value off the stack.
Data[]	pop(int size) Pop a vector of data values off the stack.
boolean	popBool() Pop a boolean.
Channel	popChannel() Pop a channel.
int	popInt() Pop an integer.
RASMCode.Label.Data	popLabel() Pop a label.
Data.List	popList() Pop a list.
Register	popRegister() Pop a register.
StringData	popString() Pop a string.
TypeData	popType() Pop a type.
Data.Union	popUnion() Pop a union.
Data.Word	popWord() Pop a word.
void	push(boolean bool) Push a single boolean onto the stack.
void	push(Data d) Push a single data value onto the stack.
void	push(Data[] dvec) Push a list of data values onto the stack.
void	push(Data[] dvec, int from, int to) Push part of a list of data values onto the stack.
void	push(int i) Push a single integer onto the stack.
void	removeTraceListener(RASMThread.TraceListener tracer) Detach a trace listener from this object.
SavedState	saveState() Save the state of this thread.
void	setContext(Object context) Set the context associated with the current instruction.
void	setIdx(int idx, Data d) Set a value at an offset from the base of the current stack-frame.
void	setLocation(RASMCode.Label label) Jump to the given label.
void	setStateless(boolean stateless) Mark this thread as being a stateless thread.
String	toString()

Methods inherited from class uk.ac.man.cs.rainbow.simulator.RainbowThread

choice, delay, execute, exitSelf, getChoice, getChoiceRange, getDirection, getFromChannel, getParent, isAvailable, putToChannel, release, scheduleChild, setChoice, signalForward, sleep, stillBusy

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RASMThread

public RASMThread(Scheduler scheduler,
                  RASMCode code)

Create a new top-level thread.

Parameters:

scheduler - The scheduler that will determine when this thread executes.

code - The block of code that this thread will start executing. The entry point is the first instruction in the block of code.

Method Detail

fork

public void fork(RASMCode.Label[] labels,
                 Data[] args)

Create a collection of child threads.

Parameters:

labels - The entry points for the child threads.

args - The initial stack contents for the child threads.

See Also:

Parallel

setStateless

public void setStateless(boolean stateless)

Mark this thread as being a stateless thread.

motionless

public void motionless()

Cause the current instruction to be repeated.

setLocation

public void setLocation(RASMCode.Label label)

Jump to the given label. Makes the location of the next instruction executed be that specified by the label.

Parameters:

label - The label to jump to.

consolidateStack

public void consolidateStack()

Trim the space allocated to the stack.

frameSize

public int frameSize()

How large is the current stack frame?

newFrame

public void newFrame()

Create a new stack frame.

oldFrame

public void oldFrame()
              throws RASMThread.Exception

Return to an old stack frame.

getIdx

public Data getIdx(int idx)
            throws RASMThread.Exception

Read a value from an offset from the base of the current stack-frame.

See Also:

GetArg

setIdx

public void setIdx(int idx,
                   Data d)
            throws RASMThread.Exception

Set a value at an offset from the base of the current stack-frame.

See Also:

PutArg

push

public void push(Data[] dvec)

Push a list of data values onto the stack. This is much more efficient than doing the items one by one, especially where the values were removed with a vector pop in the first place.

Parameters:

dvec - The array of data values to push.

See Also:

pop(int), push(Data[],int,int)

push

public void push(Data[] dvec,
                 int from,
                 int to)

Push part of a list of data values onto the stack. This is much more efficient than doing the items one by one, especially where the values were removed with a vector pop in the first place.

Parameters:

dvec - The array of data values to push part of.

from - The index of the first data value to push.

to - One more than the index of the last data value to push.

Throws:

IndexOutOfBoundsException - If the indices do not refer to places in the array (or one past) or if the starting position is beyond the finishing position.

See Also:

pop(int), push(Data[])

push

public void push(Data d)

Push a single data value onto the stack.

Parameters:

d - The data value to push.

push

public void push(boolean bool)

Push a single boolean onto the stack.

See Also:

Data.Word, Type.Boolean

push

public void push(int i)

Push a single integer onto the stack.

See Also:

Data.Word, Type.Integer

pop

public Data[] pop(int size)
           throws RASMThread.Exception

Pop a vector of data values off the stack. The argument specifies how many values to pop.

Parameters:

size - The number of data values to pop.

Returns:

An array of data values. The data value that was uppermost on the stack before the pop will be the data value that is at the end of the array.

Throws:

RASMThread.Exception - If there aren't that many data values in the current stack frame.

See Also:

push(Data[]), push(Data[],int,int)

pop

public Data pop()
         throws RASMThread.Exception

Pop a single data value off the stack.

Returns:

The data value popped.

Throws:

RASMThread.Exception - If the current stack frame is empty.

popInt

public int popInt()
           throws RASMThread.Exception

Pop an integer.

See Also:

pop()

popBool

public boolean popBool()
                throws RASMThread.Exception

Pop a boolean.

See Also:

pop()

popWord

public Data.Word popWord()
                  throws RASMThread.Exception

Pop a word.

See Also:

pop()

popList

public Data.List popList()
                  throws RASMThread.Exception

Pop a list.

See Also:

pop()

popUnion

public Data.Union popUnion()
                    throws RASMThread.Exception

Pop a union.

See Also:

pop()

popType

public TypeData popType()
                 throws RASMThread.Exception

Pop a type.

See Also:

pop()

popString

public StringData popString()
                     throws RASMThread.Exception

Pop a string.

See Also:

pop()

popLabel

public RASMCode.Label.Data popLabel()
                             throws RASMThread.Exception

Pop a label.

See Also:

pop()

popChannel

public Channel popChannel()
                   throws RASMThread.Exception

Pop a channel.

See Also:

pop()

popRegister

public Register popRegister()
                     throws RASMThread.Exception

Pop a register.

See Also:

pop()

newChannel

public Channel.Data newChannel(String name)

Create a new channel with the given name.

newRegister

public Register.Data newRegister(String name)

Create a new register with the given name.

chanContext

public Channel chanContext()
                    throws RASMThread.Exception

Get the channel from the thread context or the stack.

endContext

public boolean endContext(boolean flag)

Reset the context or repeat the instruction.

haveContext

public boolean haveContext()

Is there any context associated with the current instruction?

getContext

public Object getContext()

Retrieve the context associated with the current instruction.

setContext

public void setContext(Object context)

Set the context associated with the current instruction.

Parameters:

context - If this is null then this removes the context. Otherwise, it ensures that thread does not advance to the next instruction.

toString

public String toString()

Overrides:

toString in class RainbowThread

labelChannel

public void labelChannel(Channel chan,
                         String label)

Put a client-determined label on a channel.

labelThread

public void labelThread(Register reg,
                        String label)

Put a client-determined label on this thread. The register parameter is used to characterise the state of this thread.

keyRegister

public void keyRegister(Register reg,
                        int key)

Allow clients to inspect the given register.

See Also:

Scheduler.readKeyedRegister(int)

execExtern

public Data execExtern(String externString)
                throws RainbowException

Pass a string to the client for external execution.

See Also:

TclExec

execute

protected void execute()
                throws RainbowException

Execute this thread according to where it is in its block of code.

Overrides:

execute in class RainbowThread

Throws:

RainbowException - If something goes wrong during the execution.

characterise

public Data characterise()

Characterise this thread and its children.

Overrides:

characterise in class RainbowThread

Returns:

A data value that encapsulates the state of the thread and its children.

addTraceListener

public void addTraceListener(RASMThread.TraceListener tracer)

Attach a trace listener to this object.

Parameters:

tracer - The tracer object to attach.

See Also:

RASMThread.TraceListener, removeTraceListener(RASMThread.TraceListener)

removeTraceListener

public void removeTraceListener(RASMThread.TraceListener tracer)

Detach a trace listener from this object. Does nothing if the given tracer is not attached.

Parameters:

tracer - The tracer object to detach.

See Also:

RASMThread.TraceListener, addTraceListener(RASMThread.TraceListener)

markStaticBase

public void markStaticBase()

Mark the current point on the stack as having only unchanging values below it. This allows the optimisation of state saving.

saveState

public SavedState saveState()

Save the state of this thread.

Overrides:

saveState in class RainbowThread

Returns:

A saved state token for loading later.

See Also:

loadState(SavedState)

loadState

public void loadState(SavedState saved)

Reload a previously saved state.

Overrides:

loadState in class RainbowThread

Parameters:

saved - The saved state token to reload.

Throws:

IllegalArgumentException - If the state token was not created by this thread.

See Also:

saveState()