java.lang.Object
java.lang.Thread
org.bzdev.devqsim.TaskThread
- All Implemented Interfaces:
Runnable
Threads that can appear on a simulation's event queue.
This class provides thread-control mechanisms that ensure
that only one TaskThread runs at a time, and only when the
thread running the simulation has paused. Aside from
reducing the need for locking, this eliminates the need
for rollbacks.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
Exception used while terminating task threads.Nested classes/interfaces inherited from class java.lang.Thread
Thread.State, Thread.UncaughtExceptionHandler
-
Field Summary
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
-
Method Summary
Modifier and TypeMethodDescriptionvoid
cancel()
Cancel a task thread.static TaskThread
Get the current task thread.Get the SimObject that originated the threadGet the simulation event that will restart this thread.getTag()
Get a description of a thread.void
static void
pause
(long delay) Causes the current TaskThread to pause for a specified delay.static void
pause
(long delay, double tpriority) Causes the current TaskThread to pause for a specified delay and event priority.static boolean
pause
(TaskEventCallable callable1, SimEventCallable callable2, CallableReturns<Boolean> afterPause) Causes the current TaskThread to pause, possibly indefinitely.boolean
reschedule
(long delay) Reschedule a task thread for a specified delay.boolean
reschedule
(long delay, double tpriority) Reschedule a task thread for a specified delay and event priority.void
run()
void
start()
Methods inherited from class java.lang.Thread
activeCount, checkAccess, clone, countStackFrames, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, onSpinWait, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, stop, suspend, toString, yield
-
Method Details
-
getOriginator
Get the SimObject that originated the thread- Returns:
- the simulation object denoted as the thread's originator; null if there are none
-
getTag
Get a description of a thread.- Returns:
- a string describing the thread
-
start
public void start() -
run
public void run() -
getSimulationEvent
Get the simulation event that will restart this thread.- Returns:
- the simulation event.
-
interrupt
public void interrupt() -
cancel
public void cancel()Cancel a task thread. When called while from the thread, the thread will exit; Otherwise the thread is interrupted. Note: a TaskThread.CancelException is used to terminate the thread. This exception should not be caught (or if caught, must be rethrown). -
reschedule
public boolean reschedule(long delay) Reschedule a task thread for a specified delay. This method will fail if the current task is not already scheduled.- Parameters:
delay
- the number of simulation time units from the current simulation time at which the task will be scheduled to run- Returns:
- true on success; false on failure
-
reschedule
public boolean reschedule(long delay, double tpriority) Reschedule a task thread for a specified delay and event priority. This method will fail if the current task is not already scheduled.- Parameters:
delay
- the number of simulation time units from the current simulation time at which the task will be scheduled to runtpriority
- the event priority at the time the thread will- Returns:
- true on success; false on failure
-
currentThread
Get the current task thread.- Returns:
- the current thread
- Throws:
IllegalStateException
- the current thread is not a TaskThread
-
pause
public static boolean pause(TaskEventCallable callable1, SimEventCallable callable2, CallableReturns<Boolean> afterPause) throws IllegalStateException Causes the current TaskThread to pause, possibly indefinitely. This must be called from a TaskThread thread. When a thread is paused, a TaskThreadSimEvent is generated that allows the thread to be canceled or restarted. Sometimes it is necessary to encapsulate this event within another event for a variety of reasons such as executing additional code when an thread restarts. This is handled by three methods:- callable1. This argument makes it possible to handle the queuing or scheduling of an event. If callable1's call method, whose argument is the TaskThreadSimEvent generated, returns null, that signals that the queuing or scheduling failed (e.g., one attempted to queue the thread on a queue with a size limit that has been reached) and that the thread will simply continue executing. If callable1 itself is null, the effect is the same as if callable1's call method simply returned its argument. When callable1 is non-null and returns null, the call to 'pause' will return false; otherwise the value returned becomes the event associated with the call to 'pause'.
- callable2. This argument is intended for cases where a user wishes to keep a reference to an event so that it can be canceled. callable2's 'call' method will be called with the simulation event returned by callable1's call method (implicitly if callable1 is null), and callable2's call method is responsible for storing its argument for later use. If the argument to callable2's call method is null, the call method will not be called.
- afterPause. This argument allows code to be executed immediately before pause returns. It's call method, which takes no arguments, should return true normally, but should return false if the task should behave as if pausing, queuing, or some other operation associated with the pause, had failed.
Note: this method is intended for creating objects such as task queues. Casual use of it is discouraged. While somewhat complex, this complexity is necessary in order to handle cases such as finite queues in which an attempt to be placed on a queue may fail. The return value from a call to 'pause' returns this status information. It is worth mentioning that, unless
System.exit(int)
is called, a program will not terminate if a thread, including an instance of TaskThread, has started but has not yet terminated.- Parameters:
callable1
- a TaskEventCallable that will be given a TaskThreadSimEvent whose processEvent method restarts the current thread; null if the current TaskThreadSimEvent should be usedcallable2
- a SimEventCallable that will be given the simulation event generated by callable1; null if not providedafterPause
- a CallableReturns<Boolean> whose 'call' method will be executed just as the current thread restarts in order to determine the return value; null if the return value should always be true- Returns:
- true to indicate that processing associated with the pause succeeded; false to indicate a failure
- Throws:
IllegalStateException
- called in wrong context
-
pause
Causes the current TaskThread to pause for a specified delay. This must be called from a TaskThread thread. It is worth mentioning that, unlessSystem.exit(int)
is called, a program will not terminate if a thread, including an instance of TaskThread, has started but has not yet terminated.- Parameters:
delay
- the number of simulation time units to wait- Throws:
IllegalStateException
- called in wrong context
-
pause
Causes the current TaskThread to pause for a specified delay and event priority. This must be called from a TaskThread thread.- Parameters:
delay
- the number of simulation time units to waittpriority
- the event priority at the time the thread will resume- Throws:
IllegalStateException
- called in wrong context
-