jsr166z.forkjoin
Class ForkJoinTask<V>

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

Direct Known Subclasses:

AsyncAction, CyclicAction, LinkedAsyncAction, RecursiveAction, RecursiveTask

public abstract class ForkJoinTask<V>
extends java.lang.Object

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 the various styles of fork/join processing. Normally, a concrete ForkJoinTask subclass declares fields comprising its parameters, established in a constructor, and then defines a protected 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 in general 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 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.

Constructor Summary

ForkJoinTask()

Method Summary

void	cancel() Asserts that the results of this task's computation will not be used.
abstract java.lang.Throwable	exec() Immediately commences execution of this task by the current worker thread unless already cancelled, returning any exception thrown by its compute method.
abstract void	finish(V result) Completes this task, and if not already aborted or cancelled, returning the given result upon join and related operations.
abstract void	finishExceptionally(java.lang.Throwable ex) Completes this task abnormally, and if not already aborted or cancelled, causes it to throw the given exception upon join and related operations.
void	fork() Arranges to asynchronously execute this task, which will later be directly or indirectly joined by the caller of this method.
java.lang.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.
abstract V	invoke() Equivalent in effect to the sequence fork(); join(); but may be more efficient.
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).
boolean	isStolen() Returns true if this task was stolen from some other worker in the pool and has not yet completed.
V	join() Returns the result of the computation when it is ready.
java.lang.Throwable	quietlyJoin() Joins this task, without returning its result or throwing exception, but returning the exception that join would throw.
abstract V	rawResult() Returns the result that would be returned by join, or null if this task has not yet 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

Constructor Detail

ForkJoinTask

public ForkJoinTask()

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:

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

invoke

public abstract V invoke()

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

Returns:

the computed result

Throws:

java.lang.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).

isCancelled

public final boolean isCancelled()

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.

getException

public final java.lang.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 has not yet completed. This method is designed primarily to aid debugging, as well as to support extensions.

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 repeatedly executing pre-constructed trees of subtasks.

isStolen

public final boolean isStolen()

Returns true if this task was stolen from some other worker in the pool and has not yet completed. This method should be called only by the thread currently executing this task. The results of calling this method in any other context are undefined.

Returns:

true is this task is stolen

quietlyJoin

public final java.lang.Throwable quietlyJoin()

Joins this task, without returning its result or throwing exception, but returning the exception that join would throw. 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.

Returns:

the exception that would be thrown by join, or null if this task completed normally.

exec

public abstract java.lang.Throwable exec()

Immediately commences execution of this task by the current worker thread unless already cancelled, returning any exception thrown by its compute method.

Returns:

exception thrown by compute (or via cancellation), or null if none

finish

public abstract void finish(V result)

Completes this task, and if not already aborted or cancelled, returning the given result upon join and related operations.

Parameters:

result - the result to return

finishExceptionally

public abstract void finishExceptionally(java.lang.Throwable ex)

Completes this task abnormally, and if not already aborted or cancelled, causes it to throw the given exception upon join and related operations.

Parameters:

ex - the exception to throw. While not necessarily statically enforced, this must be a RuntimeException or Error.