abstract class RecursiveAction extends ForkJoinTask[Void]
A recursive resultless ForkJoinTask
. This class
establishes conventions to parameterize resultless actions as
Void
ForkJoinTask
s. 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
- Alphabetic
- By Inheritance
- RecursiveAction
- ForkJoinTask
- Serializable
- Future
- AnyRef
- Any
- by any2stringadd
- by StringFormat
- by Ensuring
- by ArrowAssoc
- Hide All
- Show All
- Public
- All
Instance Constructors
- new RecursiveAction()
Abstract Value Members
-
abstract
def
compute(): Unit
The main computation performed by this task.
The main computation performed by this task.
- Attributes
- protected[akka.dispatch.forkjoin]
Concrete Value Members
-
final
def
!=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
final
def
##(): Int
- Definition Classes
- AnyRef → Any
-
def
+(other: String): String
- Implicit
- This member is added by an implicit conversion from RecursiveAction to any2stringadd[RecursiveAction] performed by method any2stringadd in scala.Predef.
- Definition Classes
- any2stringadd
-
def
->[B](y: B): (RecursiveAction, B)
- Implicit
- This member is added by an implicit conversion from RecursiveAction to ArrowAssoc[RecursiveAction] performed by method ArrowAssoc in scala.Predef.
- Definition Classes
- ArrowAssoc
- Annotations
- @inline()
-
final
def
==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
final
def
asInstanceOf[T0]: T0
- Definition Classes
- Any
-
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
, andcancel
will returntrue
and calls to#join
and related methods will result inCancellationException
.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
-
def
clone(): AnyRef
- Attributes
- protected[java.lang]
- Definition Classes
- AnyRef
- Annotations
- @native() @HotSpotIntrinsicCandidate() @throws( ... )
-
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
-
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 invokesuper
implementation to maintain guarantees.- value
the result value for this task
- Definition Classes
- ForkJoinTask
-
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 invokesuper
implementation to maintain guarantees.- ex
the exception to throw. If this exception is not a
RuntimeException
orError
, the actual exception thrown will be aRuntimeException
with causeex
.
- Definition Classes
- ForkJoinTask
-
def
ensuring(cond: (RecursiveAction) ⇒ Boolean, msg: ⇒ Any): RecursiveAction
- Implicit
- This member is added by an implicit conversion from RecursiveAction to Ensuring[RecursiveAction] performed by method Ensuring in scala.Predef.
- Definition Classes
- Ensuring
-
def
ensuring(cond: (RecursiveAction) ⇒ Boolean): RecursiveAction
- Implicit
- This member is added by an implicit conversion from RecursiveAction to Ensuring[RecursiveAction] performed by method Ensuring in scala.Predef.
- Definition Classes
- Ensuring
-
def
ensuring(cond: Boolean, msg: ⇒ Any): RecursiveAction
- Implicit
- This member is added by an implicit conversion from RecursiveAction to Ensuring[RecursiveAction] performed by method Ensuring in scala.Predef.
- Definition Classes
- Ensuring
-
def
ensuring(cond: Boolean): RecursiveAction
- Implicit
- This member is added by an implicit conversion from RecursiveAction to Ensuring[RecursiveAction] performed by method Ensuring in scala.Predef.
- Definition Classes
- Ensuring
-
final
def
eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
-
def
equals(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
final
def
exec(): Boolean
Implements execution conventions for RecursiveActions.
Implements execution conventions for RecursiveActions.
- returns
true
if this task is known to have completed normally
- Attributes
- protected[akka.dispatch.forkjoin]
- Definition Classes
- RecursiveAction → ForkJoinTask
-
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
returningtrue
.- returns
this
, to simplify usage
- Definition Classes
- ForkJoinTask
-
def
formatted(fmtstr: String): String
- Implicit
- This member is added by an implicit conversion from RecursiveAction to StringFormat[RecursiveAction] performed by method StringFormat in scala.Predef.
- Definition Classes
- StringFormat
- Annotations
- @inline()
-
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 cancelledExecutionException
if the computation threw an exceptionInterruptedException
if the current thread is not a member of a ForkJoinPool and was interrupted while waitingTimeoutException
if the wait timed out
-
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 cancelledExecutionException
if the computation threw an exceptionInterruptedException
if the current thread is not a member of a ForkJoinPool and was interrupted while waiting
-
final
def
getClass(): Class[_]
- Definition Classes
- AnyRef → Any
- Annotations
- @native() @HotSpotIntrinsicCandidate()
-
final
def
getException(): Throwable
Returns the exception thrown by the base computation, or a
CancellationException
if cancelled, ornull
if none or if the method has not yet completed.Returns the exception thrown by the base computation, or a
CancellationException
if cancelled, ornull
if none or if the method has not yet completed.- returns
the exception, or
null
if none
- Definition Classes
- ForkJoinTask
-
final
def
getForkJoinTaskTag(): Short
Returns the tag for this task.
-
final
def
getRawResult(): Void
Always returns
null
. -
def
hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native() @HotSpotIntrinsicCandidate()
-
final
def
invoke(): Void
Commences performing this task, awaits its completion if necessary, and returns its result, or throws an (unchecked)
RuntimeException
orError
if the underlying computation did so.Commences performing this task, awaits its completion if necessary, and returns its result, or throws an (unchecked)
RuntimeException
orError
if the underlying computation did so.- returns
the computed result
- Definition Classes
- ForkJoinTask
-
final
def
isCancelled(): Boolean
- Definition Classes
- ForkJoinTask → Future
-
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
-
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
-
final
def
isDone(): Boolean
- Definition Classes
- ForkJoinTask → Future
-
final
def
isInstanceOf[T0]: Boolean
- Definition Classes
- Any
-
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 inRuntimeException
orError
, notExecutionException
, and that interrupts of the calling thread do not cause the method to abruptly return by throwingInterruptedException
.- returns
the computed result
- Definition Classes
- ForkJoinTask
-
final
def
ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
-
final
def
notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @HotSpotIntrinsicCandidate()
-
final
def
notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @HotSpotIntrinsicCandidate()
-
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
(ornull
by default) will be returned as the result of subsequent invocations ofjoin
and related operations.- Definition Classes
- ForkJoinTask
- Since
1.8
-
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
-
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
-
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()
reportsfalse
, andgetException()
reportsnull
. However, the value returned bygetRawResult
is unaffected. To clear this value, you can invokesetRawResult(null)
.- Definition Classes
- ForkJoinTask
-
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
-
final
def
setRawResult(mustBeNull: Void): Unit
Requires null completion value.
Requires null completion value.
- Attributes
- protected[akka.dispatch.forkjoin]
- Definition Classes
- RecursiveAction → ForkJoinTask
-
final
def
synchronized[T0](arg0: ⇒ T0): T0
- Definition Classes
- AnyRef
-
def
toString(): String
- Definition Classes
- AnyRef → Any
-
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
-
final
def
wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
final
def
wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @throws( ... )
-
final
def
wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
def
→[B](y: B): (RecursiveAction, B)
- Implicit
- This member is added by an implicit conversion from RecursiveAction to ArrowAssoc[RecursiveAction] performed by method ArrowAssoc in scala.Predef.
- Definition Classes
- ArrowAssoc