APIdia Launch Partner
Top Description Fields Constructors Methods
java.util.stream

pack-priv abstract Class AbstractTask<P_IN, P_OUT, R, K extends AbstractTask<P_IN, P_OUT, R, K>>

extends CountedCompleter<R>
Class Inheritance
Known Direct Subclasses
java.util.stream.Nodes.CollectorTask, java.util.stream.ReduceOps.ReduceTask, java.util.stream.WhileOps.DropWhileTask, java.util.stream.AbstractShortCircuitTask
Annotations
@SuppressWarnings:serial
Type Parameters
<P_IN>
Type of elements input to the pipeline
<P_OUT>
Type of elements output from the pipeline
<R>
Type of intermediate result, which may be different from operation result type
<K>
Type of parent, child and sibling tasks
Imports
java.util.Spliterator, java.util.concurrent.CountedCompleter, .ForkJoinPool, .ForkJoinWorkerThread
Abstract base class for most fork-join tasks used to implement stream ops. Manages splitting logic, tracking of child tasks, and intermediate results. Each task is associated with a Spliterator that describes the portion of the input associated with the subtree rooted at this task. Tasks may be leaf nodes (which will traverse the elements of the Spliterator) or internal nodes (which split the Spliterator into multiple child tasks).

Implementation Note

This class is based on CountedCompleter, a form of fork-join task where each task has a semaphore-like count of uncompleted children, and the task is implicitly completed and notified when its last child completes. Internal node tasks will likely override the onCompletion method from CountedCompleter to merge the results from child tasks into the current task's result.

Splitting and setting up the child task links is done by compute() for internal nodes. At compute() time for leaf nodes, it is guaranteed that the parent's child-related fields (including sibling links for the parent's children) will be set up for all children.

For example, a task that performs a reduce would override doLeaf() to perform a reduction on that leaf node's chunk using the Spliterator, and override onCompletion() to merge the results of the child tasks for internal nodes: 

protected S doLeaf() {
        spliterator.forEach(...);
        return localReductionResult;
    }

    public void onCompletion(CountedCompleter caller) {
        if (!isLeaf()) {
            ReduceTask<P_IN, P_OUT, T, R> child = children;
            R result = child.getLocalResult();
            child = child.nextSibling;
            for (; child != null; child = child.nextSibling)
                result = combine(result, child.getLocalResult());
            setLocalResult(result);
        }
    }

Serialization is not supported as there is no intention to serialize tasks managed by stream ops.

Since
1.8

Field Summary

Modifier and TypeField and Description
protected final PipelineHelper<P_OUT>
helper

The pipeline helper, common to all tasks in a computation

private static final int
LEAF_TARGET

protected K
leftChild

The left child.

private R
localResult

The result of this node, if completed

protected K
rightChild

The right child.

protected Spliterator<P_IN>
spliterator

The spliterator for the portion of the input associated with the subtree rooted at this task

protected long
targetSize

Target leaf size, common to all tasks in a computation

Constructor Summary

AccessConstructor and Description
protected
AbstractTask(PipelineHelper<P_OUT>
The PipelineHelper describing the stream pipeline up to this operation
helper, Spliterator<P_IN>
The Spliterator describing the source for this pipeline
spliterator)

Constructor for root nodes.

protected
AbstractTask(K
this node's parent task
parent, Spliterator<P_IN>
Spliterator describing the subtree rooted at this node, obtained by splitting the parent Spliterator
spliterator)

Constructor for non-root nodes.

Method Summary

Modifier and TypeMethod and Description
public void
compute()

Implements abstract java.util.concurrent.CountedCompleter.compute.

Decides whether or not to split a task further or compute it directly.

protected abstract R

Returns:

the computed result of a leaf node
doLeaf()

Computes the result associated with a leaf node.

public static int
getLeafTarget()

Default target of leaf tasks for parallel decomposition.

protected R

Returns:

local result for this node previously stored with setLocalResult
getLocalResult()

Retrieves a result previously stored with setLocalResult

protected K

Returns:

the parent of this task, or null if this task is the root
getParent()

Returns the parent of this task, or null if this task is the root

public R

Returns:

local result for this node previously stored with setLocalResult
getRawResult()

Overrides java.util.concurrent.CountedCompleter.getRawResult.

Returns the local result, if any.

protected final long
getTargetSize(long sizeEstimate)

Returns the targetSize, initializing it via the supplied size estimate if not already initialized.

protected boolean

Returns:

true if this task is a leaf node
isLeaf()

Indicates whether this task is a leaf node.

protected boolean

Returns:

true if this node is a "leftmost" node
isLeftmostNode()

Returns whether this node is a "leftmost" node -- whether the path from the root to this node involves only traversing leftmost child links.

protected boolean

Returns:

true if this task is the root node.
isRoot()

Indicates whether this task is the root node

protected abstract K

Returns:

newly constructed child node
makeChild(Spliterator<P_IN>
Spliterator describing the subtree rooted at this node, obtained by splitting the parent Spliterator
spliterator)

Constructs a new node of type T whose parent is the receiver; must call the AbstractTask(T, Spliterator) constructor with the receiver and the provided Spliterator.

public void
onCompletion(CountedCompleter<?> caller)

Overrides java.util.concurrent.CountedCompleter.onCompletion.

Performs an action when method tryComplete is invoked and the pending count is zero, or when the unconditional method complete is invoked.

protected void
setLocalResult(R
local result for this node
localResult)

Associates the result with the task, can be retrieved with getLocalResult

protected void
setRawResult(R
must be null, or an exception is thrown (this is a safety tripwire to detect when setRawResult() is being used instead of setLocalResult()
result)

Overrides java.util.concurrent.CountedCompleter.setRawResult.

Does nothing; instead, subclasses should use setLocalResult(Object) to manage results.

public static long

Returns:

suggested target leaf size
suggestTargetSize(long sizeEstimate)

Returns a suggested target leaf size based on the initial size estimate.

Inherited from java.util.concurrent.CountedCompleter:
addToPendingCountcompareAndSetPendingCountcompletedecrementPendingCountUnlessZeroexecfirstCompletegetCompletergetPendingCountgetRoothelpCompletenextCompleteonExceptionalCompletionpropagateCompletionquietlyCompleteRootsetPendingCounttryComplete

Field Detail

helperback to summary
protected final PipelineHelper<P_OUT> helper

The pipeline helper, common to all tasks in a computation

LEAF_TARGETback to summary
private static final int LEAF_TARGET
leftChildback to summary
protected K leftChild

The left child. null if no children if non-null rightChild is non-null

localResultback to summary
private R localResult

The result of this node, if completed

rightChildback to summary
protected K rightChild

The right child. null if no children if non-null leftChild is non-null

spliteratorback to summary
protected Spliterator<P_IN> spliterator

The spliterator for the portion of the input associated with the subtree rooted at this task

targetSizeback to summary
protected long targetSize

Target leaf size, common to all tasks in a computation

Constructor Detail

AbstractTaskback to summary
protected AbstractTask(PipelineHelper<P_OUT> helper, Spliterator<P_IN> spliterator)

Constructor for root nodes.

Parameters
helper:PipelineHelper<P_OUT>

The PipelineHelper describing the stream pipeline up to this operation

spliterator:Spliterator<P_IN>

The Spliterator describing the source for this pipeline

AbstractTaskback to summary
protected AbstractTask(K parent, Spliterator<P_IN> spliterator)

Constructor for non-root nodes.

Parameters
parent:K

this node's parent task

spliterator:Spliterator<P_IN>

Spliterator describing the subtree rooted at this node, obtained by splitting the parent Spliterator

Method Detail

computeback to summary
public void compute()

Implements abstract java.util.concurrent.CountedCompleter.compute.

Decides whether or not to split a task further or compute it directly. If computing directly, calls doLeaf and pass the result to setRawResult. Otherwise splits off subtasks, forking one and continuing as the other.

The method is structured to conserve resources across a range of uses. The loop continues with one of the child tasks when split, to avoid deep recursion. To cope with spliterators that may be systematically biased toward left-heavy or right-heavy splits, we alternate which child is forked versus continued in the loop.

Annotations
@Override
doLeafback to summary
protected abstract R doLeaf()

Computes the result associated with a leaf node. Will be called by compute() and the result passed to setLocalResult()

Returns:R

the computed result of a leaf node

getLeafTargetback to summary
public static int getLeafTarget()

Default target of leaf tasks for parallel decomposition. To allow load balancing, we over-partition, currently to approximately four tasks per processor, which enables others to help out if leaf tasks are uneven or some processors are otherwise busy.

getLocalResultback to summary
protected R getLocalResult()

Retrieves a result previously stored with setLocalResult

Returns:R

local result for this node previously stored with setLocalResult

getParentback to summary
protected K getParent()

Returns the parent of this task, or null if this task is the root

Returns:K

the parent of this task, or null if this task is the root

Annotations
@SuppressWarnings:unchecked
getRawResultback to summary
public R getRawResult()

Overrides java.util.concurrent.CountedCompleter.getRawResult.

Returns the local result, if any. Subclasses should use setLocalResult(Object) and getLocalResult() to manage results. This returns the local result so that calls from within the fork-join framework will return the correct result.

Returns:R

local result for this node previously stored with setLocalResult

Annotations
@Override
getTargetSizeback to summary
protected final long getTargetSize(long sizeEstimate)

Returns the targetSize, initializing it via the supplied size estimate if not already initialized.

isLeafback to summary
protected boolean isLeaf()

Indicates whether this task is a leaf node. (Only valid after compute has been called on this node). If the node is not a leaf node, then children will be non-null and numChildren will be positive.

Returns:boolean

true if this task is a leaf node

isLeftmostNodeback to summary
protected boolean isLeftmostNode()

Returns whether this node is a "leftmost" node -- whether the path from the root to this node involves only traversing leftmost child links. For a leaf node, this means it is the first leaf node in the encounter order.

Returns:boolean

true if this node is a "leftmost" node

isRootback to summary
protected boolean isRoot()

Indicates whether this task is the root node

Returns:boolean

true if this task is the root node.

makeChildback to summary
protected abstract K makeChild(Spliterator<P_IN> spliterator)

Constructs a new node of type T whose parent is the receiver; must call the AbstractTask(T, Spliterator) constructor with the receiver and the provided Spliterator.

Parameters
spliterator:Spliterator<P_IN>

Spliterator describing the subtree rooted at this node, obtained by splitting the parent Spliterator

Returns:K

newly constructed child node

onCompletionback to summary
public void onCompletion(CountedCompleter<?> caller)

Overrides java.util.concurrent.CountedCompleter.onCompletion.

Doc from java.util.concurrent.CountedCompleter.onCompletion.

Performs an action when method tryComplete is invoked and the pending count is zero, or when the unconditional method complete is invoked. By default, this method does nothing. You can distinguish cases by checking the identity of the given caller argument. If not equal to this, then it is typically a subtask that may contain results (and/or links to other results) to combine.

Implementation Note

Clears spliterator and children fields. Overriders MUST call super.onCompletion as the last thing they do if they want these cleared.

Annotations
@Override
setLocalResultback to summary
protected void setLocalResult(R localResult)

Associates the result with the task, can be retrieved with getLocalResult

Parameters
localResult:R

local result for this node

setRawResultback to summary
protected void setRawResult(R result)

Overrides java.util.concurrent.CountedCompleter.setRawResult.

Does nothing; instead, subclasses should use setLocalResult(Object) to manage results.

Parameters
result:R

must be null, or an exception is thrown (this is a safety tripwire to detect when setRawResult() is being used instead of setLocalResult()

Annotations
@Override
suggestTargetSizeback to summary
public static long suggestTargetSize(long sizeEstimate)

Returns a suggested target leaf size based on the initial size estimate.

Returns:long

suggested target leaf size