Class TaskThread

java.lang.Object
java.lang.Thread
org.bzdev.devqsim.TaskThread
All Implemented Interfaces:
Runnable

public class TaskThread extends Thread
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:
  • Method Details

    • getOriginator

      public SimObject getOriginator()
      Get the SimObject that originated the thread
      Returns:
      the simulation object denoted as the thread's originator; null if there are none
    • getTag

      public String getTag()
      Get a description of a thread.
      Returns:
      a string describing the thread
    • start

      public void start()
      Overrides:
      start in class Thread
    • run

      public void run()
      Specified by:
      run in interface Runnable
      Overrides:
      run in class Thread
    • getSimulationEvent

      public TaskSimulationEvent getSimulationEvent()
      Get the simulation event that will restart this thread.
      Returns:
      the simulation event.
    • interrupt

      public void interrupt()
      Overrides:
      interrupt in class Thread
    • 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 run
      tpriority - the event priority at the time the thread will
      Returns:
      true on success; false on failure
    • currentThread

      public static TaskThread currentThread() throws IllegalStateException
      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 used
      callable2 - a SimEventCallable that will be given the simulation event generated by callable1; null if not provided
      afterPause - 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

      public static void pause(long delay) throws IllegalStateException
      Causes the current TaskThread to pause for a specified delay. This must be called from a TaskThread thread. 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:
      delay - the number of simulation time units to wait
      Throws:
      IllegalStateException - called in wrong context
    • pause

      public static void pause(long delay, double tpriority) throws IllegalStateException
      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 wait
      tpriority - the event priority at the time the thread will resume
      Throws:
      IllegalStateException - called in wrong context