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 submitted
 to a ForkJoinPool.  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 intended 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
 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. Tasks should also not perform
 blocking IO, and should ideally access variables that are
 completely independent of those accessed by other running
 tasks. Minor breaches of these restrictions, for example using
 shared output streams, may be tolerable in practice, but frequent
 use may result in poor performance, and the potential to
 indefinitely stall if the number of threads not waiting for IO or
 other external synchronization becomes exhausted. This usage
 restriction is in part 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.
 
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.
 
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 computations that do not return results, or
 RecursiveTask for those that do.  Normally, a concrete
 ForkJoinTask subclass declares fields comprising its parameters,
 established in a constructor, and then defines a compute
 method that somehow uses the control methods supplied by this base
 class. While these methods have public access (to allow
 instances of different task subclasses to call each other's
 methods), some of them may only be called from within other
 ForkJoinTasks (as may be determined using method inForkJoinPool()).  Attempts to invoke them in other contexts
 result in exceptions or errors, possibly including
 ClassCastException.
 
Method join() and its variants are appropriate for use
 only when completion dependencies are acyclic; that is, the
 parallel computation can be described as a directed acyclic graph
 (DAG). Otherwise, executions may encounter a form of deadlock as
 tasks cyclically wait for each other.  However, this framework
 supports other methods and techniques (for example the use of
 Phaser, helpQuiesce(), and complete(V)) that
 may be of use in constructing custom subclasses for problems that
 are not statically structured as DAGs.
 
Most base support methods are final, to prevent
 overriding of implementations that are intrinsically tied to the
 underlying lightweight task scheduling framework.  Developers
 creating new basic styles of fork/join processing should minimally
 implement protected methods exec(), setRawResult(V), and getRawResult(), while also introducing
 an abstract computational method that can be implemented in its
 subclasses, possibly relying on other protected methods
 provided by this class.
 
ForkJoinTasks should perform relatively small amounts of computation. Large tasks should be split into smaller subtasks, usually via recursive decomposition. As a very rough rule of thumb, a task should perform more than 100 and less than 10000 basic computational steps, and should avoid indefinite looping. If tasks are too big, then parallelism cannot improve throughput. If too small, then memory and internal task maintenance overhead may overwhelm processing.
This class provides adapt methods for Runnable
 and Callable, that may be of use when mixing execution of
 ForkJoinTasks with other kinds of tasks. When all tasks are
 of this form, consider using a pool constructed in asyncMode.
 
ForkJoinTasks are Serializable, which enables them to be
 used in extensions such as remote execution frameworks. It is
 sensible to serialize tasks only before or after, but not during,
 execution. Serialization is not relied on during execution itself.
| Constructor and Description | 
|---|
| ForkJoinTask() | 
| Modifier and Type | Method and Description | 
|---|---|
| static <T> ForkJoinTask<T> | adapt(Callable<? extends T> callable)Returns a new  ForkJoinTaskthat performs thecallmethod of the givenCallableas its action, and returns
 its result uponjoin(), translating any checked exceptions
 encountered intoRuntimeException. | 
| static ForkJoinTask<?> | adapt(Runnable runnable)Returns a new  ForkJoinTaskthat performs therunmethod of the givenRunnableas its action, and returns
 a null result uponjoin(). | 
| static <T> ForkJoinTask<T> | adapt(Runnable runnable,
     T result)Returns a new  ForkJoinTaskthat performs therunmethod of the givenRunnableas its action, and returns
 the given result uponjoin(). | 
| boolean | cancel(boolean mayInterruptIfRunning)Attempts to cancel execution of this task. | 
| void | complete(V value)Completes this task, and if not already aborted or cancelled,
 returning the given value as the result of subsequent
 invocations of  joinand related operations. | 
| void | completeExceptionally(Throwable ex)Completes this task abnormally, and if not already aborted or
 cancelled, causes it to throw the given exception upon
  joinand related operations. | 
| protected abstract boolean | exec()Immediately performs the base action of this task. | 
| ForkJoinTask<V> | fork()Arranges to asynchronously execute this task. | 
| V | get()Waits if necessary for the computation to complete, and then
 retrieves its result. | 
| V | get(long timeout,
   TimeUnit unit)Waits if necessary for at most the given time for the computation
 to complete, and then retrieves its result, if available. | 
| Throwable | getException()Returns the exception thrown by the base computation, or a
  CancellationExceptionif cancelled, ornullif
 none or if the method has not yet completed. | 
| static ForkJoinPool | getPool()Returns the pool hosting the current task execution, or null
 if this task is executing outside of any ForkJoinPool. | 
| static int | getQueuedTaskCount()Returns an estimate of the number of tasks that have been
 forked by the current worker thread but not yet executed. | 
| abstract V | getRawResult()Returns the result that would be returned by  join(), even
 if this task completed abnormally, ornullif this task
 is not known to have been completed. | 
| static int | getSurplusQueuedTaskCount()Returns an estimate of how many more locally queued tasks are
 held by the current worker thread than there are other worker
 threads that might steal them. | 
| static void | helpQuiesce()Possibly executes tasks until the pool hosting the current task
  is quiescent. | 
| static boolean | inForkJoinPool()Returns  trueif the current thread is aForkJoinWorkerThreadexecuting as a ForkJoinPool computation. | 
| V | invoke()Commences performing this task, awaits its completion if
 necessary, and returns its result, or throws an (unchecked)
  RuntimeExceptionorErrorif the underlying
 computation did so. | 
| static <T extends ForkJoinTask<?>>  | invokeAll(Collection<T> tasks)Forks all tasks in the specified collection, returning when
  isDoneholds for each task or an (unchecked) exception
 is encountered, in which case the exception is rethrown. | 
| static void | invokeAll(ForkJoinTask<?>... tasks)Forks the given tasks, returning when  isDoneholds for
 each task or an (unchecked) exception is encountered, in which
 case the exception is rethrown. | 
| static void | invokeAll(ForkJoinTask<?> t1,
         ForkJoinTask<?> t2)Forks the given tasks, returning when  isDoneholds for
 each task or an (unchecked) exception is encountered, in which
 case the exception is rethrown. | 
| boolean | isCancelled()Returns true if this task was cancelled before it completed
 normally. | 
| boolean | isCompletedAbnormally()Returns  trueif this task threw an exception or was cancelled. | 
| boolean | isCompletedNormally()Returns  trueif this task completed without throwing an
 exception and was not cancelled. | 
| boolean | isDone()Returns true if this task completed. | 
| V | join()Returns the result of the computation when it  is
 done. | 
| protected static ForkJoinTask<?> | peekNextLocalTask()Returns, but does not unschedule or execute, a task queued by
 the current thread but not yet executed, if one is immediately
 available. | 
| protected static ForkJoinTask<?> | pollNextLocalTask()Unschedules and returns, without executing, the next task
 queued by the current thread but not yet executed. | 
| protected static ForkJoinTask<?> | pollTask()Unschedules and returns, without executing, the next task
 queued by the current thread but not yet executed, if one is
 available, or if not available, a task that was forked by some
 other thread, if available. | 
| void | quietlyInvoke()Commences performing this task and awaits its completion if
 necessary, without returning its result or throwing its
 exception. | 
| void | quietlyJoin()Joins this task, without returning its result or throwing its
 exception. | 
| void | reinitialize()Resets the internal bookkeeping state of this task, allowing a
 subsequent  fork. | 
| protected abstract void | setRawResult(V value)Forces the given value to be returned as a result. | 
| boolean | tryUnfork()Tries to unschedule this task for execution. | 
public final ForkJoinTask<V> fork()
join() or related methods, or a call to isDone() returning true.
 This method may be invoked only from within ForkJoinPool computations (as may be determined using method
 inForkJoinPool()).  Attempts to invoke in other contexts
 result in exceptions or errors, possibly including ClassCastException.
this, to simplify usagepublic final V join()
is
 done.  This method differs from get() in that
 abnormal completion results in RuntimeException or
 Error, not ExecutionException, and that
 interrupts of the calling thread do not cause the
 method to abruptly return by throwing InterruptedException.public final V invoke()
RuntimeException or Error if the underlying
 computation did so.public static void invokeAll(ForkJoinTask<?> t1, ForkJoinTask<?> t2)
isDone holds for
 each task or an (unchecked) exception is encountered, in which
 case the exception is rethrown. If more than one task
 encounters an exception, then this method throws any one of
 these exceptions. If any task encounters an exception, the
 other may be cancelled. However, the execution status of
 individual tasks is not guaranteed upon exceptional return. The
 status of each task may be obtained using getException() and related methods to check if they have been
 cancelled, completed normally or exceptionally, or left
 unprocessed.
 This method may be invoked only from within ForkJoinPool computations (as may be determined using method
 inForkJoinPool()).  Attempts to invoke in other contexts
 result in exceptions or errors, possibly including ClassCastException.
t1 - the first taskt2 - the second taskNullPointerException - if any task is nullpublic static void invokeAll(ForkJoinTask<?>... tasks)
isDone holds for
 each task or an (unchecked) exception is encountered, in which
 case the exception is rethrown. If more than one task
 encounters an exception, then this method throws any one of
 these exceptions. If any task encounters an exception, others
 may be cancelled. However, the execution status of individual
 tasks is not guaranteed upon exceptional return. The status of
 each task may be obtained using getException() and
 related methods to check if they have been cancelled, completed
 normally or exceptionally, or left unprocessed.
 This method may be invoked only from within ForkJoinPool computations (as may be determined using method
 inForkJoinPool()).  Attempts to invoke in other contexts
 result in exceptions or errors, possibly including ClassCastException.
tasks - the tasksNullPointerException - if any task is nullpublic static <T extends ForkJoinTask<?>> Collection<T> invokeAll(Collection<T> tasks)
isDone holds for each task or an (unchecked) exception
 is encountered, in which case the exception is rethrown. If
 more than one task encounters an exception, then this method
 throws any one of these exceptions. If any task encounters an
 exception, others may be cancelled. However, the execution
 status of individual tasks is not guaranteed upon exceptional
 return. The status of each task may be obtained using getException() and related methods to check if they have been
 cancelled, completed normally or exceptionally, or left
 unprocessed.
 This method may be invoked only from within ForkJoinPool computations (as may be determined using method
 inForkJoinPool()).  Attempts to invoke in other contexts
 result in exceptions or errors, possibly including ClassCastException.
tasks - the collection of tasksNullPointerException - if tasks or any element are nullpublic boolean cancel(boolean mayInterruptIfRunning)
cancel is called, execution of
 this task is suppressed. After this method returns
 successfully, unless there is an intervening call to reinitialize(), subsequent calls to isCancelled(),
 isDone(), and cancel will return true
 and calls to join() and related methods will result in
 CancellationException.
 This method may be overridden in subclasses, but if so, must
 still ensure that these properties hold. In particular, the
 cancel method itself must not throw exceptions.
 
This method is designed to be invoked by other
 tasks. To terminate the current task, you can just return or
 throw an unchecked exception from its computation method, or
 invoke completeExceptionally(java.lang.Throwable).
public final boolean isDone()
Futurepublic final boolean isCancelled()
FutureisCancelled in interface Future<V>public final boolean isCompletedAbnormally()
true if this task threw an exception or was cancelled.true if this task threw an exception or was cancelledpublic final boolean isCompletedNormally()
true if this task completed without throwing an
 exception and was not cancelled.true if this task completed without throwing an
 exception and was not cancelledpublic final Throwable getException()
CancellationException if cancelled, or null if
 none or if the method has not yet completed.null if nonepublic void completeExceptionally(Throwable ex)
join and related operations. This method may be used
 to induce exceptions in asynchronous tasks, or to force
 completion of tasks that would not otherwise complete.  Its use
 in other situations is discouraged.  This method is
 overridable, but overridden versions must invoke super
 implementation to maintain guarantees.ex - the exception to throw. If this exception is not a
 RuntimeException or Error, the actual exception
 thrown will be a RuntimeException with cause ex.public void complete(V value)
join and related operations. This method
 may be used to provide results for asynchronous tasks, or to
 provide alternative handling for tasks that would not otherwise
 complete normally. Its use in other situations is
 discouraged. This method is overridable, but overridden
 versions must invoke super implementation to maintain
 guarantees.value - the result value for this taskpublic final V get() throws InterruptedException, ExecutionException
get in interface Future<V>CancellationException - if the computation was cancelledExecutionException - if the computation threw an
 exceptionInterruptedException - if the current thread is not a
 member of a ForkJoinPool and was interrupted while waitingpublic final V get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException
get in interface Future<V>timeout - the maximum time to waitunit - the time unit of the timeout argumentCancellationException - if the computation was cancelledExecutionException - if the computation threw an
 exceptionInterruptedException - if the current thread is not a
 member of a ForkJoinPool and was interrupted while waitingTimeoutException - if the wait timed outpublic final void quietlyJoin()
public final void quietlyInvoke()
public static void helpQuiesce()
is quiescent. This method may
 be of use in designs in which many tasks are forked, but none
 are explicitly joined, instead executing them until all are
 processed.
 This method may be invoked only from within ForkJoinPool computations (as may be determined using method
 inForkJoinPool()).  Attempts to invoke in other contexts
 result in exceptions or errors, possibly including ClassCastException.
public void reinitialize()
fork. This method allows repeated reuse of
 this task, but only if reuse occurs when this task has either
 never been forked, or has been forked, then completed and all
 outstanding joins of this task have also completed. Effects
 under any other usage conditions are not guaranteed.
 This method may be useful when executing
 pre-constructed trees of subtasks in loops.
 Upon completion of this method, isDone() reports
 false, and getException() reports null. However, the value returned by getRawResult is
 unaffected. To clear this value, you can invoke setRawResult(null).
public static ForkJoinPool getPool()
null if noneinForkJoinPool()public static boolean inForkJoinPool()
true if the current thread is a ForkJoinWorkerThread executing as a ForkJoinPool computation.true if the current thread is a ForkJoinWorkerThread executing as a ForkJoinPool computation,
 or false otherwisepublic boolean tryUnfork()
This method may be invoked only from within ForkJoinPool computations (as may be determined using method
 inForkJoinPool()).  Attempts to invoke in other contexts
 result in exceptions or errors, possibly including ClassCastException.
true if unforkedpublic static int getQueuedTaskCount()
This method may be invoked only from within ForkJoinPool computations (as may be determined using method
 inForkJoinPool()).  Attempts to invoke in other contexts
 result in exceptions or errors, possibly including ClassCastException.
public static int getSurplusQueuedTaskCount()
This method may be invoked only from within ForkJoinPool computations (as may be determined using method
 inForkJoinPool()).  Attempts to invoke in other contexts
 result in exceptions or errors, possibly including ClassCastException.
public abstract V getRawResult()
join(), even
 if this task completed abnormally, or null if this task
 is not known to have been completed.  This method is designed
 to aid debugging, as well as to support extensions. Its use in
 any other context is discouraged.null if not completedprotected abstract void setRawResult(V value)
value - the valueprotected abstract boolean exec()
complete(V) to become joinable. It may also throw an
 (unchecked) exception to indicate abnormal exit.true if completed normallyprotected static ForkJoinTask<?> peekNextLocalTask()
This method may be invoked only from within ForkJoinPool computations (as may be determined using method
 inForkJoinPool()).  Attempts to invoke in other contexts
 result in exceptions or errors, possibly including ClassCastException.
null if none are availableprotected static ForkJoinTask<?> pollNextLocalTask()
This method may be invoked only from within ForkJoinPool computations (as may be determined using method
 inForkJoinPool()).  Attempts to invoke in other contexts
 result in exceptions or errors, possibly including ClassCastException.
null if none are availableprotected static ForkJoinTask<?> pollTask()
null result does not necessarily imply quiescence
 of the pool this task is operating in.  This method is designed
 primarily to support extensions, and is unlikely to be useful
 otherwise.
 This method may be invoked only from within ForkJoinPool computations (as may be determined using method
 inForkJoinPool()).  Attempts to invoke in other contexts
 result in exceptions or errors, possibly including ClassCastException.
null if none are availablepublic static ForkJoinTask<?> adapt(Runnable runnable)
ForkJoinTask that performs the run
 method of the given Runnable as its action, and returns
 a null result upon join().runnable - the runnable actionpublic static <T> ForkJoinTask<T> adapt(Runnable runnable, T result)
ForkJoinTask that performs the run
 method of the given Runnable as its action, and returns
 the given result upon join().runnable - the runnable actionresult - the result upon completionpublic static <T> ForkJoinTask<T> adapt(Callable<? extends T> callable)
ForkJoinTask that performs the call
 method of the given Callable as its action, and returns
 its result upon join(), translating any checked exceptions
 encountered into RuntimeException.callable - the callable action Submit a bug or feature 
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
 Copyright © 1993, 2014, Oracle and/or its affiliates.  All rights reserved.