jsr166z.forkjoin
Class RecursiveTask<V>

java.lang.Object
  extended by jsr166z.forkjoin.ForkJoinTask<V>
      extended by jsr166z.forkjoin.RecursiveTask<V>

public abstract class RecursiveTask<V>
extends ForkJoinTask<V>

Recursive result-bearing ForkJoinTasks.

For a classic example, here is a task computing Fibonacci numbers:

 class Fibonacci extends RecursiveTask<Integer> {
   final int n;
   Fibonnaci(int n) { this.n = n; }
   Integer compute() {
     if (n <= 1)
        return n;
     Fibonacci f1 = new Fibonacci(n - 1);
     f1.fork();
     Fibonacci f2 = new Fibonacci(n - 2);
     return f2.invoke() + f1.join();
   }
 }
 
However, besides being a dumb way to compute Fibonacci functions (there is a simple fast linear algorithm that you'd use in practice), this is likely to perform poorly because the smallest subtasks are too small to be worthwhile splitting up. Instead, as is the case for nearly all fork/join applications, you'd pick some minimum granularity size (for example 10 here) for which you always sequentially solve rather than subdividing. Note also the use of f2.invoke() instead of f2.fork(); f2.join(), which is both more convenient and more efficient.


Constructor Summary
RecursiveTask()
           
 
Method Summary
protected abstract  V compute()
          The main computation performed by this task.
 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.
 void finish(V result)
          Completes this task, and if not already aborted or cancelled, returning the given result upon join and related operations.
 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.
 V invoke()
          Equivalent in effect to the sequence fork(); join(); but may be more efficient.
 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 jsr166z.forkjoin.ForkJoinTask
cancel, fork, getException, isCancelled, isDone, isStolen, join, quietlyJoin
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RecursiveTask

public RecursiveTask()
Method Detail

compute

protected abstract V compute()
The main computation performed by this task. While you must define this method, you should not in general call it directly. To immediately perform the computation, use invoke.

Returns:
result of the computation

rawResult

public final V rawResult()
Description copied from class: ForkJoinTask
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.

Specified by:
rawResult in class ForkJoinTask<V>
Returns:
the result, or null if not completed.

invoke

public final V invoke()
Description copied from class: ForkJoinTask
Equivalent in effect to the sequence fork(); join(); but may be more efficient.

Specified by:
invoke in class ForkJoinTask<V>
Returns:
the computed result

exec

public final java.lang.Throwable exec()
Description copied from class: ForkJoinTask
Immediately commences execution of this task by the current worker thread unless already cancelled, returning any exception thrown by its compute method.

Specified by:
exec in class ForkJoinTask<V>
Returns:
exception thrown by compute (or via cancellation), or null if none

finish

public final void finish(V result)
Description copied from class: ForkJoinTask
Completes this task, and if not already aborted or cancelled, returning the given result upon join and related operations.

Specified by:
finish in class ForkJoinTask<V>
Parameters:
result - the result to return

finishExceptionally

public final void finishExceptionally(java.lang.Throwable ex)
Description copied from class: ForkJoinTask
Completes this task abnormally, and if not already aborted or cancelled, causes it to throw the given exception upon join and related operations.

Specified by:
finishExceptionally in class ForkJoinTask<V>
Parameters:
ex - the exception to throw. While not necessarily statically enforced, this must be a RuntimeException or Error.

reinitialize

public final void reinitialize()
Description copied from class: ForkJoinTask
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.

Overrides:
reinitialize in class ForkJoinTask<V>