RecursiveTask

AI-generated Key Takeaways

• RecursiveTask is a class in Java that's used for computations that can be broken down into smaller, similar subtasks, often used in the Fork/Join framework.

• It extends ForkJoinTask and provides a mechanism for recursively splitting work and combining results.

• The compute() method is where you define the core logic of your task, breaking it down into smaller subtasks if necessary and combining their results.

• You should carefully consider the minimum size of subtasks to avoid performance issues due to excessive overhead from creating too many small tasks.

• RecursiveTask is designed for tasks that return a result; for tasks without a result, use RecursiveAction.

public abstract class RecursiveTask extends ForkJoinTask<V>

A recursive result-bearing ForkJoinTask.

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

 class Fibonacci extends RecursiveTask<Integer> {
   final int n;
   Fibonacci(int n) { this.n = n; }
   protected Integer compute() {
     if (n <= 1)
       return n;
     Fibonacci f1 = new Fibonacci(n - 1);
     f1.fork();
     Fibonacci f2 = new Fibonacci(n - 2);
     return f2.compute() + 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.

Public Constructor Summary

RecursiveTask()

Public Method Summary

final V

getRawResult() Returns the result that would be returned by join(), even if this task completed abnormally, or null if this task is not known to have been completed.

Protected Method Summary

abstract V	compute() The main computation performed by this task.
final boolean	exec() Implements execution conventions for RecursiveTask.
final void	setRawResult(V value) Forces the given value to be returned as a result.

Inherited Method Summary

From class java.util.concurrent.ForkJoinTask

static <T> ForkJoinTask<T>	adapt(Runnable runnable, T result) Returns a new ForkJoinTask that performs the run method of the given Runnable as its action, and returns the given result upon join().
static ForkJoinTask<?>	adapt(Runnable runnable) Returns a new ForkJoinTask that performs the run method of the given Runnable as its action, and returns a null result upon join().
static <T> ForkJoinTask<T>	adapt(Callable<? extends T> callable) Returns a new 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.
boolean	cancel(boolean mayInterruptIfRunning) Attempts to cancel execution of this task.
final boolean	compareAndSetForkJoinTaskTag(short expect, short update) Atomically conditionally sets the tag value for 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 join and 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 join and related operations.
abstract boolean	exec() Immediately performs the base action of this task and returns true if, upon return from this method, this task is guaranteed to have completed normally.
final ForkJoinTask<V>	fork() Arranges to asynchronously execute this task in the pool the current task is running in, if applicable, or using the ForkJoinPool.commonPool() if not inForkJoinPool().
final 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.
final V	get() Waits if necessary for the computation to complete, and then retrieves its result.
final Throwable	getException() Returns the exception thrown by the base computation, or a CancellationException if cancelled, or null if none or if the method has not yet completed.
final short	getForkJoinTaskTag() Returns the tag for this task.
static ForkJoinPool	getPool() Returns the pool hosting the current thread, or null if the current thread 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, or null if 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, or zero if this thread is not operating in a ForkJoinPool.
static void	helpQuiesce() Possibly executes tasks until the pool hosting the current task {@linkplain ForkJoinPool#isQuiescent is quiescent}.
static boolean	inForkJoinPool() Returns true if the current thread is a ForkJoinWorkerThread executing as a ForkJoinPool computation.
final V	invoke() Commences performing this task, awaits its completion if necessary, and returns its result, or throws an (unchecked) RuntimeException or Error if the underlying computation did so.
static void	invokeAll(ForkJoinTask...<?> tasks) Forks the given tasks, returning when isDone holds 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 isDone holds for each task or an (unchecked) exception is encountered, in which case the exception is rethrown.
static <T extends ForkJoinTask<?>> Collection<T>	invokeAll(Collection<T> tasks) Forks all tasks in the specified collection, returning when isDone holds for each task or an (unchecked) exception is encountered, in which case the exception is rethrown.
final boolean	isCancelled() Returns true if this task was cancelled before it completed normally.
final boolean	isCompletedAbnormally() Returns true if this task threw an exception or was cancelled.
final boolean	isCompletedNormally() Returns true if this task completed without throwing an exception and was not cancelled.
final boolean	isDone() Returns true if this task completed.
final V	join() Returns the result of the computation when it is done.
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.
static ForkJoinTask<?>	pollNextLocalTask() Unschedules and returns, without executing, the next task queued by the current thread but not yet executed, if the current thread is operating in a ForkJoinPool.
static ForkJoinTask<?>	pollTask() If the current thread is operating in a ForkJoinPool, 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.
final void	quietlyComplete() Completes this task normally without setting a value.
final void	quietlyInvoke() Commences performing this task and awaits its completion if necessary, without returning its result or throwing its exception.
final 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.
final short	setForkJoinTaskTag(short newValue) Atomically sets the tag value for this task and returns the old value.
abstract void	setRawResult(V value) Forces the given value to be returned as a result.
boolean	tryUnfork() Tries to unschedule this task for execution.

From class java.lang.Object

Object	clone() Creates and returns a copy of this Object.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of Class that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

From interface java.util.concurrent.Future

abstract boolean	cancel(boolean mayInterruptIfRunning) Attempts to cancel execution of this task.
abstract 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.
abstract V	get() Waits if necessary for the computation to complete, and then retrieves its result.
abstract boolean	isCancelled() Returns true if this task was cancelled before it completed normally.
abstract boolean	isDone() Returns true if this task completed.

Public Constructors

public RecursiveTask ()

Public Methods

public final V getRawResult ()

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

Returns

• the result, or null if not completed

Protected Methods

protected abstract V compute ()

The main computation performed by this task.

Returns

• the result of the computation

protected final boolean exec ()

Implements execution conventions for RecursiveTask.

Returns

• true if this task is known to have completed normally

protected final void setRawResult (V value)

Forces the given value to be returned as a result. This method is designed to support extensions, and should not in general be called otherwise.

Parameters

value	the value