jsr166y.forkjoin
Class ForkJoinTask<V>

java.lang.Object
  jsr166y.forkjoin.ForkJoinTask<V>

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

AsyncAction, RecursiveAction, RecursiveTask

public abstract class ForkJoinTask<V>
extends Object
implements Serializable

Abstract base class for tasks that run within a 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.

The ForkJoinTask class is not directly subclassable outside of this package. Instead, you can subclass one of the supplied abstract classes that support various styles of fork/join processing. 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, most may only be called from within other ForkJoinTasks. Attempts to invoke them in other contexts result in exceptions or errors including ClassCastException. The only generally accessible methods are those for cancellation and status checking. The only way to invoke a "main" driver task is to submit it to a ForkJoinPool. Normally, once started, this will in turn start other subtasks. Nearly all of these base support methods are final because their implementations are intrinsically tied to the underlying lightweight task scheduling framework, and so cannot be overridden.

ForkJoinTasks play similar roles as Futures but support a more limited range of use. The "lightness" of ForkJoinTasks is due to a set of restrictions (that are only partially statically enforceable) reflecting their intended use as purely computational tasks -- calculating pure functions or operating on purely isolated objects. The only coordination mechanisms supported for ForkJoinTasks are fork, that arranges asynchronous execution, and join, that doesn't proceed until the task's result has been computed. (A simple form of cancellation is also supported). The computation defined in the compute method should not in general perform any other form of blocking synchronization, should not perform IO, and should be independent of other tasks. Minor breaches of these restrictions, for example using shared output streams, may be tolerable in practice, but frequent use will result in poor performance, and the potential to indefinitely stall if the number of threads not waiting for 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 join them. These exceptions may additionally include RejectedExecutionExceptions stemming from internal resource exhaustion such as failure to allocate internal task queues.

ForkJoinTasks should perform relatively small amounts of computations, othewise splitting into smaller tasks. As a very rough rule of thumb, a task should perform more than 100 and less than 10000 basic computational steps. If tasks are too big, then parellelism cannot improve throughput. If too small, then memory and internal task maintenance overhead may overwhelm processing. The ForkJoinWorkerThread class supports a number of inspection and tuning methods that can be useful when developing fork/join programs.

ForkJoinTasks are Serializable, which enables them to be used in extensions such as remote execution frameworks. However, it is in general safe to serialize tasks only before or after, but not during execution. Serialization is not relied on during execution itself.

See Also:

Serialized Form

Method Summary

void	cancel() Asserts that the results of this task's computation will not be used.
void	fork() Arranges to asynchronously execute this task, which will later be directly or indirectly joined by the caller of this method.
V	forkJoin() Equivalent in effect to the sequence fork(); join(); but likely to be more efficient.
Throwable	getException() Returns the exception thrown by method compute, or a CancellationException if cancelled, or null if none or if the method has not yet completed.
boolean	isCancelled() Returns true if this task was cancelled.
boolean	isDone() Returns true if the computation performed by this task has completed (or has been cancelled).
V	join() Returns the result of the computation when it is ready.
void	quietlyJoin() Joins this task, without returning its result or throwing an exception.
abstract V	rawResult() Returns the result that would be returned by join, or null if this task is not known to have been completed.
void	reinitialize() Resets the internal bookkeeping state of this task, allowing a subsequent fork.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

fork

public final void fork()

Arranges to asynchronously execute this task, which will later be directly or indirectly joined by the caller of this method. While it is not necessarily enforced, it is a usage error to fork a task more than once unless it has completed and been reinitialized. This method may be invoked only from within other ForkJoinTask computations. Attempts to invoke in other contexts result in exceptions or errors including ClassCastException.

join

public final V join()

Returns the result of the computation when it is ready. Monitoring note: Callers of this method need not block, but may instead assist in performing computations that may directly or indirectly cause the result to be ready. This method may be invoked only from within other ForkJoinTask computations. Attempts to invoke in other contexts result in exceptions or errors including ClassCastException.

Returns:

the computed result

Throws:

Throwable - (a RuntimeException, Error, or unchecked exception) if the underlying computation did so.

forkJoin

public V forkJoin()

Equivalent in effect to the sequence fork(); join(); but likely to be more efficient.

Returns:

the computed result

Throws:

Throwable - (a RuntimeException, Error, or unchecked exception) if the underlying computation did so.

isDone

public final boolean isDone()

Returns true if the computation performed by this task has completed (or has been cancelled).

Returns:

true if this computation has completed

isCancelled

public final boolean isCancelled()

Returns true if this task was cancelled.

Returns:

true if this task was cancelled

cancel

public void cancel()

Asserts that the results of this task's computation will not be used. If a cancellation occurs before this task is processed, then its compute method will not be executed, isCancelled will report true, and join will result in a CancellationException being thrown. Otherwise, there are no guarantees about whether isCancelled will report true, whether join will return normally or via an exception, or whether these behaviors will remain consistent upon repeated invocation. This method may be overridden in subclasses, but if so, must still ensure that these minimal properties hold.

This method is designed to be invoked by other tasks. To abruptly terminate the current task, you should just return from its computation method, or throw new CancellationException(), or in AsyncActions, invoke finishExceptionally().

getException

public final Throwable getException()

Returns the exception thrown by method compute, or a CancellationException if cancelled, or null if none or if the method has not yet completed.

Returns:

the exception, or null if none

rawResult

public abstract V rawResult()

Returns the result that would be returned by join, 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 strongly discouraged.

Returns:

the result, or null if not completed.

reinitialize

public void reinitialize()

Resets the internal bookkeeping state of this task, allowing a subsequent 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, and are almost surely wrong. This method may be useful when executing pre-constructed trees of subtasks in loops.

quietlyJoin

public final void quietlyJoin()

Joins this task, without returning its result or throwing an exception. This method may be useful when processing collections of tasks when some have been cancelled or otherwise known to have aborted. This method may be invoked only from within other ForkJoinTask computations. Attempts to invoke in other contexts result in exceptions or errors including ClassCastException.