public abstract class ForkJoinTask<V> extends Object implements Future<V>, Serializable
ForkJoinPool.
A ForkJoinTask is a thread-like entity that is much
lighter weight than a normal thread. Huge numbers of tasks and
subtasks may be hosted by a small number of actual threads in a
ForkJoinPool, at the price of some usage limitations.
A "main" ForkJoinTask begins execution when it is
explicitly submitted to a ForkJoinPool, or, if not already
engaged in a ForkJoin computation, commenced in the ForkJoinPool.commonPool() via fork(), invoke(), or
related methods. Once started, it will usually in turn start other
subtasks. As indicated by the name of this class, many programs
using ForkJoinTask employ only methods fork() and
join(), or derivatives such as invokeAll. However, this class also
provides a number of other methods that can come into play in
advanced usages, as well as extension mechanics that allow support
of new forms of fork/join processing.
A ForkJoinTask is a lightweight form of Future.
The efficiency of ForkJoinTasks stems from a set of
restrictions (that are only partially statically enforceable)
reflecting their main use as computational tasks calculating pure
functions or operating on purely isolated objects. The primary
coordination mechanisms are fork(), that arranges
asynchronous execution, and join(), that doesn't proceed
until the task's result has been computed. Computations should
ideally avoid synchronized methods or blocks, and should
minimize other blocking synchronization apart from joining other
tasks or using synchronizers such as Phasers that are advertised to
cooperate with fork/join scheduling. Subdividable tasks should also
not perform blocking I/O, and should ideally access variables that
are completely independent of those accessed by other running
tasks. These guidelines are loosely enforced by not permitting
checked exceptions such as IOExceptions to be
thrown. However, computations may still encounter unchecked
exceptions, that are rethrown to callers attempting to join
them. These exceptions may additionally include RejectedExecutionException stemming from internal resource
exhaustion, such as failure to allocate internal task
queues. Rethrown exceptions behave in the same way as regular
exceptions, but, when possible, contain stack traces (as displayed
for example using ex.printStackTrace()) of both the thread
that initiated the computation as well as the thread actually
encountering the exception; minimally only the latter.
It is possible to define and use ForkJoinTasks that may block,
but doing do requires three further considerations: (1) Completion
of few if any other tasks should be dependent on a task
that blocks on external synchronization or I/O. Event-style async
tasks that are never joined (for example, those subclassing CountedCompleter) often fall into this category. (2) To minimize
resource impact, tasks should be small; ideally performing only the
(possibly) blocking action. (3) Unless the ForkJoinPool.ManagedBlocker API is used, or the number of possibly
blocked tasks is known to be less than the pool's ForkJoinPool.getParallelism() level, the pool cannot guarantee that
enough threads will be available to ensure progress or good
performance.
The primary method for awaiting completion and extracting
results of a task is join(), but there are several variants:
The Future.get() methods support interruptible and/or timed
waits for completion and report results using Future
conventions. Method invoke() is semantically
equivalent to fork(); join() but always attempts to begin
execution in the current thread. The "quiet" forms of
these methods do not extract results or report exceptions. These
may be useful when a set of tasks are being executed, and you need
to delay processing of results or exceptions until all complete.
Method invokeAll (available in multiple versions)
performs the most common form of parallel invocation: forking a set
of tasks and joining them all.
In the most typical usages, a fork-join pair act like a call
(fork) and return (join) from a parallel recursive function. As is
the case with other forms of recursive calls, returns (joins)
should be performed innermost-first. For example, a.fork();
b.fork(); b.join(); a.join(); is likely to be substantially more
efficient than joining a before b.
The execution status of tasks may be queried at several levels
of detail: isDone() is true if a task completed in any way
(including the case where a task was cancelled without executing);
isCompletedNormally() is true if a task completed without
cancellation or encountering an exception; isCancelled() is
true if the task was cancelled (in which case getException()
returns a CancellationException); and
isCompletedAbnormally() is true if a task was either
cancelled or encountered an exception, in which case getException() will return either the encountered exception or
CancellationException.
The ForkJoinTask class is not usually directly subclassed.
Instead, you subclass one of the abstract classes that support a
particular style of fork/join processing, typically RecursiveAction for most computations that do not return results,
RecursiveTask for those that do, and CountedCompleter for those in which completed actions trigger
other actions. Normally, a concrete ForkJoinTask subclass declares
fields c