jsr166y.forkjoin
public abstract class LinkedAsyncAction extends ForkJoinTask<java.lang.Void>
Upon construction, an LinkedAsyncAction may register as a subtask of a given parent task. In this case, completion of this task will propagate to its parent. If the parent's pending subtask completion count becomes zero, it too will finish. LinkedAsyncActions rarely use methods join or invoke but instead propagate completion to parents implicitly via finish. While typical, it is not necessary for each task to finish itself. For example, it is possible to treat one subtask as a continuation of the current task by not registering it on construction. In this case, a finish of the subtask will trigger finish of the parent without the parent explicitly doing so.
In addition to supporting these different computation styles compared to Recursive tasks, LinkedAsyncActions may have smaller stack space footprints while executing, but may have greater per-task overhead.
Sample Usage. Here is a sketch of an LinkedAsyncAction that visits all of the nodes of a graph. The details of the graph's Node and Edge classes are omitted, but we assume each node contains an AtomicBoolean mark that starts out false. To execute this, you would create a GraphVisitor for the root node with null parent, and invoke in a ForkJoinPool. Upon return, all reachable nodes will have been visited.
class GraphVisitor extends LinkedAsyncAction { final Node node; GraphVisitor(GraphVistor parent, Node node) { super(parent); this.node = node; } protected void compute() { if (node.mark.compareAndSet(false, true)) { for (Edge e : node.edges()) { Node dest = e.getDestination(); if (!dest.mark.get()) new GraphVisitor(this, dest).fork(); } visit(node); } finish(); } }
Modifier | Constructor and Description |
---|---|
protected |
LinkedAsyncAction()
Creates a new action with no parent.
|
protected |
LinkedAsyncAction(LinkedAsyncAction parent)
Creates a new action with the given parent.
|
protected |
LinkedAsyncAction(LinkedAsyncAction parent,
boolean register)
Creates a new action with the given parent, optionally
registering with the parent.
|
protected |
LinkedAsyncAction(LinkedAsyncAction parent,
boolean register,
int pending)
Creates a new action with the given parent, optionally
registering with the parent, and setting the pending join count
to the given value.
|
Modifier and Type | Method and Description |
---|---|
protected abstract void |
compute()
The asynchronous part of the 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()
Equivalent to finish(null).
|
void |
finish(java.lang.Void result)
Completes this task.
|
void |
finishExceptionally(java.lang.Throwable ex)
Completes this task abnormally.
|
java.lang.Void |
forkJoin()
Equivalent in effect to the sequence fork(); join();
but may be more efficient.
|
LinkedAsyncAction |
getParent()
Returns this task's parent, or null if none.
|
int |
getPendingSubtaskCount()
Returns the number of subtasks that have not yet completed.
|
protected void |
onCompletion()
Overridable callback action triggered by finish.
|
protected boolean |
onException()
Overridable callback action triggered by
finishExceptionally.
|
java.lang.Void |
rawResult()
Always returns null.
|
void |
reinitialize()
Resets the internal bookkeeping state of this task, maintaining
the current parent but clearing pending joins.
|
void |
reinitialize(int pending)
Resets the internal bookkeeping state of this task, maintaining
the current parent and setting pending joins to the given value.
|
void |
reinitialize(LinkedAsyncAction parent,
boolean register)
Reinitialize with the given parent, optionally registering.
|
void |
reinitialize(LinkedAsyncAction parent,
boolean register,
int pending)
Reinitialize with the given parent, optionally registering
and setting pending join count.
|
cancel, fork, getException, isCancelled, isDone, isStolen, join, quietlyJoin
protected LinkedAsyncAction()
protected LinkedAsyncAction(LinkedAsyncAction parent)
parent
- the parent task, or null if noneprotected LinkedAsyncAction(LinkedAsyncAction parent, boolean register)
parent
- the parent task, or null if noneregister
- true if parent must wait for this task
to complete before it completesprotected LinkedAsyncAction(LinkedAsyncAction parent, boolean register, int pending)
parent
- the parent task, or null if noneregister
- true if parent must wait for this task
to complete before it completespending
- the pending join countprotected abstract void compute()
protected void onCompletion()
protected boolean onException()
public final void finish()
public final void finish(java.lang.Void result)
finish
in class ForkJoinTask<java.lang.Void>
result
- must be null.public final void finishExceptionally(java.lang.Throwable ex)
finishExceptionally
in class ForkJoinTask<java.lang.Void>
ex
- the exception to throw when joining this taskjava.lang.NullPointerException
- if ex is nulljava.lang.Throwable
- if any invocation of
onException does so.public final LinkedAsyncAction getParent()
public final int getPendingSubtaskCount()
public final java.lang.Void rawResult()
rawResult
in class ForkJoinTask<java.lang.Void>
public void reinitialize()
reinitialize
in class ForkJoinTask<java.lang.Void>
public void reinitialize(int pending)
pending
- the number of pending joinspublic void reinitialize(LinkedAsyncAction parent, boolean register)
parent
- the parent task, or null if noneregister
- true if parent must wait for this task
to complete before it completespublic void reinitialize(LinkedAsyncAction parent, boolean register, int pending)
parent
- the parent task, or null if noneregister
- true if parent must wait for this task
to complete before it completespending
- the pending join countpublic final java.lang.Void forkJoin()
ForkJoinTask
forkJoin
in class ForkJoinTask<java.lang.Void>
public final java.lang.Throwable exec()
ForkJoinTask
exec
in class ForkJoinTask<java.lang.Void>