Packages

c

akka.dispatch.forkjoin

RecursiveAction

abstract class RecursiveAction extends ForkJoinTask[Void]

A recursive resultless ForkJoinTask. This class establishes conventions to parameterize resultless actions as Void ForkJoinTasks. Because null is the only valid value of type Void, methods such as join always return null upon completion.

Sample Usages. Here is a simple but complete ForkJoin sort that sorts a given long[] array:

 
static class SortTask extends RecursiveAction {
  final long[] array; final int lo, hi;
  SortTask(long[] array, int lo, int hi) {
    this.array = array; this.lo = lo; this.hi = hi;
  
  SortTask(long[] array) { this(array, 0, array.length); }
  protected void compute() {
    if (hi - lo < THRESHOLD)
      sortSequentially(lo, hi);
    else {
      int mid = (lo + hi) >>> 1;
      invokeAll(new SortTask(array, lo, mid),
                new SortTask(array, mid, hi));
      merge(lo, mid, hi);
    }
  }
  // implementation details follow:
  final static int THRESHOLD = 1000;
  void sortSequentially(int lo, int hi) {
    Arrays.sort(array, lo, hi);
  }
  void merge(int lo, int mid, int hi) {
    long[] buf = Arrays.copyOfRange(array, lo, mid);
    for (int i = 0, j = lo, k = mid; i < buf.length; j++)
      array[j] = (k == hi || buf[i] < array[k]) ?
        buf[i++] : array[k++];
  }
}}

You could then sort anArray by creating new SortTask(anArray) and invoking it in a ForkJoinPool. As a more concrete simple example, the following task increments each element of an array:

 
class IncrementTask extends RecursiveAction {
  final long[] array; final int lo, hi;
  IncrementTask(long[] array, int lo, int hi) {
    this.array = array; this.lo = lo; this.hi = hi;
  
  protected void compute() {
    if (hi - lo < THRESHOLD) {
      for (int i = lo; i < hi; ++i)
        array[i]++;
    }
    else {
      int mid = (lo + hi) >>> 1;
      invokeAll(new IncrementTask(array, lo, mid),
                new IncrementTask(array, mid, hi));
    }
  }
}}

The following example illustrates some refinements and idioms that may lead to better performance: RecursiveActions need not be fully recursive, so long as they maintain the basic divide-and-conquer approach. Here is a class that sums the squares of each element of a double array, by subdividing out only the right-hand-sides of repeated divisions by two, and keeping track of them with a chain of next references. It uses a dynamic threshold based on method getSurplusQueuedTaskCount, but counterbalances potential excess partitioning by directly performing leaf actions on unstolen tasks rather than further subdividing.

 
double sumOfSquares(ForkJoinPool pool, double[] array) {
  int n = array.length;
  Applyer a = new Applyer(array, 0, n, null);
  pool.invoke(a);
  return a.result;


class Applyer extends RecursiveAction {
  final double[] array;
  final int lo, hi;
  double result;
  Applyer next; // keeps track of right-hand-side tasks
  Applyer(double[] array, int lo, int hi, Applyer next) {
    this.array = array; this.lo = lo; this.hi = hi;
    this.next = next;
  }

  double atLeaf(int l, int h) {
    double sum = 0;
    for (int i = l; i < h; ++i) // perform leftmost base step
      sum += array[i] * array[i];
    return sum;
  }

  protected void compute() {
    int l = lo;
    int h = hi;
    Applyer right = null;
    while (h - l > 1 && getSurplusQueuedTaskCount() <= 3) {
       int mid = (l + h) >>> 1;
       right = new Applyer(array, mid, h, right);
       right.fork();
       h = mid;
    }
    double sum = atLeaf(l, h);
    while (right != null) {
       if (right.tryUnfork()) // directly calculate if not stolen
         sum += right.atLeaf(right.lo, right.hi);
      else {
         right.join();
         sum += right.result;
       }
       right = right.next;
     }
    result = sum;
  }
}}

Source
RecursiveAction.java
Since

1.7

Linear Supertypes
Type Hierarchy
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. RecursiveAction
  2. ForkJoinTask
  3. Serializable
  4. Future
  5. AnyRef
  6. Any
Implicitly
  1. by any2stringadd
  2. by StringFormat
  3. by Ensuring
  4. by ArrowAssoc
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Instance Constructors

  1. new RecursiveAction()

Concrete Value Members

  1. def cancel(mayInterruptIfRunning: Boolean): Boolean

    Attempts to cancel execution of this task.

    Attempts to cancel execution of this task. This attempt will fail if the task has already completed or could not be cancelled for some other reason. If successful, and this task has not started when 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.

    mayInterruptIfRunning

    this value has no effect in the default implementation because interrupts are not used to control cancellation.

    returns

    true if this task is now cancelled

    Definition Classes
    ForkJoinTask → Future
  2. final def compareAndSetForkJoinTaskTag(e: Short, tag: Short): Boolean

    Atomically conditionally sets the tag value for this task.

    Atomically conditionally sets the tag value for this task. Among other applications, tags can be used as visit markers in tasks operating on graphs, as in methods that check: if (task.compareAndSetForkJoinTaskTag((short)0, (short)1)) before processing, otherwise exiting because the node has already been visited.

    e

    the expected tag value

    tag

    the new tag value

    returns

    true if successful; i.e., the current value was equal to e and is now tag.

    Definition Classes
    ForkJoinTask
    Since

    1.8

  3. def complete(value: Void): Unit

    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.

    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. 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 task

    Definition Classes
    ForkJoinTask
  4. def completeExceptionally(ex: Throwable): Unit

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

    Completes this task abnormally, and if not already aborted or cancelled, causes it to throw the given exception upon 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.

    Definition Classes
    ForkJoinTask
  5. final def fork(): ForkJoinTask[Void]

    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.

    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. 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. Subsequent modifications to the state of this task or any data it operates on are not necessarily consistently observable by any thread other than the one executing it unless preceded by a call to #join or related methods, or a call to #isDone returning true.

    returns

    this, to simplify usage

    Definition Classes
    ForkJoinTask
  6. final def get(timeout: Long, unit: TimeUnit): Void

    Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.

    Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.

    timeout

    the maximum time to wait

    unit

    the time unit of the timeout argument

    returns

    the computed result

    Definition Classes
    ForkJoinTask → Future
    Exceptions thrown

    CancellationException if the computation was cancelled

    ExecutionException if the computation threw an exception

    InterruptedException if the current thread is not a member of a ForkJoinPool and was interrupted while waiting

    TimeoutException if the wait timed out

  7. final def get(): Void

    Waits if necessary for the computation to complete, and then retrieves its result.

    Waits if necessary for the computation to complete, and then retrieves its result.

    returns

    the computed result

    Definition Classes
    ForkJoinTask → Future
    Exceptions thrown

    CancellationException if the computation was cancelled

    ExecutionException if the computation threw an exception

    InterruptedException if the current thread is not a member of a ForkJoinPool and was interrupted while waiting

  8. final def getException(): Throwable

    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.

    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.

    returns

    the exception, or null if none

    Definition Classes
    ForkJoinTask
  9. final def getForkJoinTaskTag(): Short

    Returns the tag for this task.

    Returns the tag for this task.

    returns

    the tag for this task

    Definition Classes
    ForkJoinTask
    Since

    1.8

  10. final def getRawResult(): Void

    Always returns null.

    Always returns null.

    returns

    null always

    Definition Classes
    RecursiveActionForkJoinTask
  11. final def invoke(): Void

    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.

    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.

    returns

    the computed result

    Definition Classes
    ForkJoinTask
  12. final def isCancelled(): Boolean
    Definition Classes
    ForkJoinTask → Future
  13. final def isCompletedAbnormally(): Boolean

    Returns true if this task threw an exception or was cancelled.

    Returns true if this task threw an exception or was cancelled.

    returns

    true if this task threw an exception or was cancelled

    Definition Classes
    ForkJoinTask
  14. final def isCompletedNormally(): Boolean

    Returns true if this task completed without throwing an exception and was not cancelled.

    Returns true if this task completed without throwing an exception and was not cancelled.

    returns

    true if this task completed without throwing an exception and was not cancelled

    Definition Classes
    ForkJoinTask
  15. final def isDone(): Boolean
    Definition Classes
    ForkJoinTask → Future
  16. final def join(): Void

    Returns the result of the computation when it is done.

    Returns the result of the computation when it 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.

    returns

    the computed result

    Definition Classes
    ForkJoinTask
  17. final def quietlyComplete(): Unit

    Completes this task normally without setting a value.

    Completes this task normally without setting a value. The most recent value established by #setRawResult (or null by default) will be returned as the result of subsequent invocations of join and related operations.

    Definition Classes
    ForkJoinTask
    Since

    1.8

  18. final def quietlyInvoke(): Unit

    Commences performing this task and awaits its completion if necessary, without returning its result or throwing its exception.

    Commences performing this task and awaits its completion if necessary, without returning its result or throwing its exception.

    Definition Classes
    ForkJoinTask
  19. final def quietlyJoin(): Unit

    Joins this task, without returning its result or throwing its exception.

    Joins this task, without returning its result or throwing its exception. This method may be useful when processing collections of tasks when some have been cancelled or otherwise known to have aborted.

    Definition Classes
    ForkJoinTask
  20. def reinitialize(): Unit

    Resets the internal bookkeeping state of this task, allowing a subsequent fork.

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

    Definition Classes
    ForkJoinTask
  21. final def setForkJoinTaskTag(tag: Short): Short

    Atomically sets the tag value for this task.

    Atomically sets the tag value for this task.

    tag

    the tag value

    returns

    the previous value of the tag

    Definition Classes
    ForkJoinTask
    Since

    1.8

  22. def tryUnfork(): Boolean

    Tries to unschedule this task for execution.

    Tries to unschedule this task for execution. This method will typically (but is not guaranteed to) succeed if this task is the most recently forked task by the current thread, and has not commenced executing in another thread. This method may be useful when arranging alternative local processing of tasks that could have been, but were not, stolen.

    returns

    true if unforked

    Definition Classes
    ForkJoinTask