Package edu.cnu.mdi.sim.task

Class TaskHandle<R>

java.lang.Object
edu.cnu.mdi.sim.task.TaskHandle<R>
Type Parameters:
R - task result type
public final class TaskHandle<R> extends Object
Controls and observes one execution of a typed BackgroundTask.

A handle is single-use. Calling start() more than once is safe but only the first call starts a worker thread. The task runs on the daemon thread owned by an internal SimulationEngine; all TaskListener callbacks run on Swing's event-dispatch thread.

Cancellation is cooperative. cancel() sets a flag immediately, but the task must periodically inspect its TaskContext to finish promptly. The result and failure accessors are safe to read from any thread after completion because their backing fields are published with volatile semantics.

  • Constructor Details

    • TaskHandle

      public TaskHandle(BackgroundTask<R> task)
      Creates an unstarted handle with quiet, automatically running defaults. Periodic simulation refresh and heartbeat events are disabled; explicit task progress, messages, and refresh requests remain available.
      Parameters:
      task - computation to execute
      Throws:
      NullPointerException - if task is null

    • TaskHandle

      public TaskHandle(BackgroundTask<R> task, SimulationEngineConfig config)
      Creates an unstarted handle with an explicit engine configuration.

      The configuration must use automatic running because a one-shot task has no separate READY/RUN user gesture. This restriction prevents a task from appearing to start while silently waiting in the simulation READY state.

      Parameters:
      task - computation to execute
      config - engine scheduling and notification configuration; its SimulationEngineConfig.autoRun field must be true
      Throws:
      NullPointerException - if either argument is null
      IllegalArgumentException - if automatic running is disabled

  • Method Details

    • start

      public void start()
      Starts this task unless it was already started.

    • cancel

      public void cancel()
      Requests cooperative cancellation. Repeated calls are harmless. Cancellation before start() prevents the task body from running.

    • addListener

      public void addListener(TaskListener<R> listener)
      Adds a listener if the same instance is not already registered. Registration does not replay events that occurred earlier.
      Parameters:
      listener - listener to add; null is ignored

    • removeListener

      public void removeListener(TaskListener<R> listener)
      Removes a listener. @param listener listener to remove

    • getState

      public SimulationState getState()
      Returns:
      current underlying engine state

    • getCompletionStatus

      public CompletionStatus getCompletionStatus()
      Returns the terminal outcome, or null while execution is pending.
      Returns:
      terminal status or null

    • isCompleted

      public boolean isCompleted()
      Returns:
      true after any terminal outcome has been published

    • getResult

      public R getResult()
      Returns the task result. A successful task is permitted to return null; callers should inspect getCompletionStatus() to distinguish that result from an incomplete or failed task.
      Returns:
      result value, or null

    • getFailure

      public Throwable getFailure()
      Returns:
      failure, or null unless completion status is FAILED

    • getElapsedSeconds

      public double getElapsedSeconds()
      Returns:
      elapsed worker time in seconds

    • awaitTermination

      public boolean awaitTermination(long timeoutMillis) throws InterruptedException
      Waits for the worker thread to finish. This method does not flush pending EDT callbacks; use listener latches when a test must wait for UI delivery.
      Parameters:
      timeoutMillis - maximum wait, or zero to wait indefinitely
      Returns:
      true if the worker has terminated
      Throws:
      InterruptedException - if interrupted while waiting

    • getSimulationEngine

      public SimulationEngine getSimulationEngine()
      Exposes the underlying engine for advanced integration with existing MDI simulation listeners and diagnostics. Application code should normally use this handle's typed API.
      Returns:
      engine owned by this handle