Package com.tccc.kos.commons.util.concurrent.future

Class ParallelFuture

java.lang.Object
com.tccc.kos.commons.util.concurrent.future.FutureWork
com.tccc.kos.commons.util.concurrent.future.ParallelFuture
All Implemented Interfaces:
Abortable, Cancelable, Terminable, Runnable
public class ParallelFuture extends FutureWork
Allows a collection of individual futures to be run in parallel, where the overall state of ParallelFuture reflects the result of the child futures. All child futures are executed in the scheduler thread pool to ensure clean decoupling from event threads that may be used to finalize the state of the future.

Cancelling this future will cancel all running children.

The end state of this future is SUCCESS if all children are SUCCESS.

The end state in case of FAIL or ABORT can be set to achieve the desired outcome.

Since:
1.0
Version:
2022-05-05

  • Field Details

  • Constructor Details

    • ParallelFuture

      public ParallelFuture(String name)
      Creates a ParallelFuture to hold all child futures.
      Parameters:
      name - the name (for diagnostic data)

  • Method Details

    • isTerminateOnFail

      public boolean isTerminateOnFail()
      If true, cancel all child futures if any individual child future fails.

    • setTerminatelOnFail

      public void setTerminatelOnFail(boolean enable)
      If true, cancel all child futures if any individual child future fails, otherwise ignore failed children and allow all other children to complete.
      Parameters:
      enable - true to cancel children if any child fails

    • isTerminateOnAbort

      public boolean isTerminateOnAbort()
      If true, cancel all child futures if any individual child future aborts.

    • setTermianteOnAbort

      public void setTermianteOnAbort(boolean enable)
      If true, cancel all child futures if any individual child future aborts, otherwise ignore failed children and allow all other children to complete.
      Parameters:
      enable - true to cancel children if any child aborts

    • setFailState

      public void setFailState(FutureState state)
      Sets the end state to use for the parent future if any child future fails. By default the end state will be FAIL but it can be set to ABORT . This does not impact whether the children continue to run, just what the final end state will be.
      Parameters:
      state - either ABORT or FAIL

    • setAbortState

      public void setAbortState(FutureState state)
      Sets the end state to use for the parent future if any child future aborts. By default the end state will be ABORT but it can be set to FAIL . This does not impact whether the children continue to run, just what the final end state will be.
      Parameters:
      state - either abort or fail

    • setRunnable

      public FutureWork setRunnable(FutureRunnable runnable)
      Description copied from class: FutureWork
      Sets the runnable to be performed by the work. Unlike Java futures, it is possible for this work to complete without changing the end state. For example, this work may simply kick off a hardware process and some other mechanism is used to determine when that hardware is done, and that will change the state.

      This runnable can set the state, but callbacks won't be triggered until this function returns. This prevents race conditions between this code and any state event callbacks.

      If this runnable throws an exception, then the state is set to "aborted".

      Overrides:
      setRunnable in class FutureWork
      Parameters:
      runnable - the code to run as part of the work

    • fail

      public void fail(String reason)
      Description copied from class: FutureWork
      Fails the work with the specified reason.
      Overrides:
      fail in class FutureWork
      Parameters:
      reason - the fail reason

    • success

      public void success()
      Description copied from class: FutureWork
      Marks the work "successful".
      Overrides:
      success in class FutureWork

    • add

      public void add(FutureWork future)
      Adds a future to the collection. Futures can only be added before processing starts.
      Parameters:
      future - the work to add to the sequence

    • getEstimatedTimeMs

      public long getEstimatedTimeMs()
      When running in parallel, the estimated completion time is equal to the longest child task.
      Overrides:
      getEstimatedTimeMs in class FutureWork
      Returns:
      the estimated time of the operation