com.newisys.eventsim
Class SimulationThread

java.lang.Object
  com.newisys.eventsim.SimulationThread

public final class SimulationThread
extends Object

Represents a thread of execution in a simulation.

Note: This class does not extend java.lang.Thread to avoid exposing Thread methods that should not be used with simulation threads.

Method Summary

static SimulationThread	currentThread() Returns the current simulation thread.
static SimulationThread	currentThreadOrNull() Returns the current simulation thread, or null if the current thread is not a simulation thread.
static SimulationThread	forThread(Thread javaThread) Returns the simulation thread object corresponding to the given Java thread.
static SimulationThread	forThreadOrNull(Thread javaThread) Returns the simulation thread object corresponding to the given Java thread, or null if the given thread is not a simulation thread.
List<SimulationThread>	getChildren() Returns a list of child threads (i.e.
Event	getJoinEvent() Returns the event that will be notified when this thread terminates.
SimulationManager	getManager() Returns the SimulationManager that manages this thread.
String	getName() Returns the name of this thread.
SimulationThread	getParent() Returns the parent thread of this simulation thread, or null if this is a top-level thread (created by a non-simulation thread).
PRNG	getRandom() Returns the random number generator for this thread.
PRNGFactory	getRandomFactory() Returns the factory used to create random number generators for child threads.
ThreadState	getState() Returns the current state of this thread.
void	join() Waits until this thread terminates.
void	join(SimulationThread thread) Waits until the given thread has terminated.
void	joinAll(Collection<SimulationThread> threads) Waits until all of the threads in the given collection have terminated.
void	joinAll(SimulationThread... threads) Waits until all of the given threads have terminated.
void	joinAny(Collection<SimulationThread> threads) Waits until any of the threads in the given collection have terminated.
void	joinAny(SimulationThread... threads) Waits until any of the given threads have terminated.
void	joinChildren() Waits until all of the current child threads of this thread (and their descendents) have terminated.
void	setRandom(PRNG random) Sets the random number generator for this thread.
void	setRandomFactory(PRNGFactory randomFactory) Sets the factory used to create random number generators for child threads.
void	terminate() Terminates this thread, either immediately if it currently PENDING or BLOCKED, or at its next synchronization point if it is RUNNING, and waits for the thread to become TERMINATED.
void	terminateChildren() Terminates all of the child threads of this thread (and their descendents) by calling the terminate() method on them.
String	toString()
void	waitFor(Event e) Waits until the given event occurs.
void	waitForAll(Collection<? extends Event> events) Waits until all of the events in the given collection have occurred.
void	waitForAll(Event... events) Waits until all of the given events have occurred.
void	waitForAny(Collection<? extends Event> events) Waits until any of the events in the given collection have occurred.
void	waitForAny(Event... events) Waits until any of the given events have occurred.
void	yield() Suspends this simulation thread until all other currently runnable threads have had a chance to run.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

currentThread

public static SimulationThread currentThread()

Returns the current simulation thread. This method throws an IllegalThreadException if the current thread is not associated with a simulation thread.

Returns:

the SimulationThread currently running

Throws:

IllegalThreadException

currentThreadOrNull

public static SimulationThread currentThreadOrNull()

Returns the current simulation thread, or null if the current thread is not a simulation thread.

Returns:

the SimulationThread currently running or null

forThread

public static SimulationThread forThread(Thread javaThread)

Returns the simulation thread object corresponding to the given Java thread. This method throws an IllegalThreadException if the given thread is not associated with a simulation thread.

Parameters:

javaThread - a Java thread

Returns:

the SimulationThread currently running

Throws:

IllegalThreadException

forThreadOrNull

public static SimulationThread forThreadOrNull(Thread javaThread)

Returns the simulation thread object corresponding to the given Java thread, or null if the given thread is not a simulation thread.

Parameters:

javaThread - a Java thread

Returns:

the SimulationThread currently running or null

getName

public String getName()

Returns the name of this thread.

Returns:

the name of this thread.

getManager

public SimulationManager getManager()

Returns the SimulationManager that manages this thread.

Returns:

the SimulationManager for this thread

getParent

public SimulationThread getParent()

Returns the parent thread of this simulation thread, or null if this is a top-level thread (created by a non-simulation thread).

Returns:

the parent RealSimulationThread or null

getChildren

public List<SimulationThread> getChildren()

Returns a list of child threads (i.e. threads directly created by this thread). The returned list is a snapshot of the current child threads at the time of the call.

Returns:

a List of SimulationThreads

getState

public ThreadState getState()

Returns the current state of this thread.

Returns:

the current state of this thread

getJoinEvent

public Event getJoinEvent()

Returns the event that will be notified when this thread terminates.

Returns:

the join event for this thread

getRandom

public PRNG getRandom()

Returns the random number generator for this thread.

Returns:

the PRNG instance for this thread

setRandom

public void setRandom(PRNG random)

Sets the random number generator for this thread.

Parameters:

random - a new PRNG instance for this thread

getRandomFactory

public PRNGFactory getRandomFactory()

Returns the factory used to create random number generators for child threads.

Returns:

the PRNGFactory instance for this thread

setRandomFactory

public void setRandomFactory(PRNGFactory randomFactory)

Sets the factory used to create random number generators for child threads.

Parameters:

randomFactory - a new PRNGFactory instance for this thread

yield

public void yield()

Suspends this simulation thread until all other currently runnable threads have had a chance to run.

This method must be called from the Java thread associated with this simulation thread.

waitFor

public void waitFor(Event e)

Waits until the given event occurs.

This method must be called from the Java thread associated with this simulation thread.

Parameters:

e - the event to wait for

waitForAny

public void waitForAny(Event... events)

Waits until any of the given events have occurred.

This method must be called from the Java thread associated with this simulation thread.

Parameters:

events - an array of events to wait on

waitForAny

public void waitForAny(Collection<? extends Event> events)

Waits until any of the events in the given collection have occurred.

This method must be called from the Java thread associated with this simulation thread.

Parameters:

events - a collection of events to wait on

waitForAll

public void waitForAll(Event... events)

Waits until all of the given events have occurred.

This method must be called from the Java thread associated with this simulation thread.

Parameters:

events - an array of events to wait on

waitForAll

public void waitForAll(Collection<? extends Event> events)

Waits until all of the events in the given collection have occurred.

This method must be called from the Java thread associated with this simulation thread.

Parameters:

events - a collection of events to wait on

join

public void join()

Waits until this thread terminates.

This method must be called from a Java thread other than the one associated with this simulation thread.

joinChildren

public void joinChildren()

Waits until all of the current child threads of this thread (and their descendents) have terminated. Specifically, this method performs a depth-first recursive join of each thread in the tree of descendents. For each thread, it first takes a snapshot of the current list of children, before recursively joining them. This implies that if a thread creates new threads while it is being joined, those threads will not be joined.

join

public void join(SimulationThread thread)

Waits until the given thread has terminated.

This method must be called from the Java thread associated with this simulation thread.

Parameters:

thread - the thread to wait on

joinAny

public void joinAny(SimulationThread... threads)

Waits until any of the given threads have terminated.

This method must be called from the Java thread associated with this simulation thread.

Parameters:

threads - an array of threads to join

joinAny

public void joinAny(Collection<SimulationThread> threads)

Waits until any of the threads in the given collection have terminated.

This method must be called from the Java thread associated with this simulation thread.

Parameters:

threads - a collection of threads to join

joinAll

public void joinAll(SimulationThread... threads)

Waits until all of the given threads have terminated.

This method must be called from the Java thread associated with this simulation thread.

Parameters:

threads - an array of threads to join

joinAll

public void joinAll(Collection<SimulationThread> threads)

Waits until all of the threads in the given collection have terminated.

This method must be called from the Java thread associated with this simulation thread.

Parameters:

threads - a collection of threads to join

terminate

public void terminate()

Terminates this thread, either immediately if it currently PENDING or BLOCKED, or at its next synchronization point if it is RUNNING, and waits for the thread to become TERMINATED. This method does nothing if this thread is already TERMINATED or is terminating.

This method may be called from any thread.

terminateChildren

public void terminateChildren()

Terminates all of the child threads of this thread (and their descendents) by calling the terminate() method on them. Specifically, this method performs a pre-order recursive terminate of each thread in the tree of descendents.

For each thread, it first takes a snapshot of the current list of children, before recursively terminating them. This implies that if a thread creates new threads before it terminates, those threads will not be terminated.

This method may be called from any thread.

toString

public String toString()

Overrides:

toString in class Object