ion 1 if (hi - lo >= 2) { int mid=(lo + hi) >>> 1; setPendingCount(2); // must set pending count before fork new ForEach(this, array, op, mid, hi).fork(); // right child new ForEach(this, array, op, lo, mid).fork(); // left child } else if (hi > lo) op.apply(array[lo]); tryComplete(); } }} This design can be improved by noticing that in the recursive case, the task has nothing to do after forking its right task, so can directly invoke its left task before returning. (This is an analog of tail recursion removal.) Also, because the task returns upon executing its left task (rather than falling through to invoke {@code tryComplete}) the pending count is set to one:
{@code class ForEach ...}public void compute() // version 2 if (hi - lo >= 2) { int mid = (lo + hi) >>> 1; setPendingCount(1); // only one pending new ForEach(this, array, op, mid, hi).fork(); // right child new ForEach(this, array, op, lo, mid).compute(); // direct invoke } else { if (hi > lo) op.apply(array[lo]); tryComplete(); } } } As a further improvement, notice that the left task need not even exist. Instead of creating a new one, we can iterate using the original task, and add a pending count for each fork. Additionally, because no task in this tree implements an {@link #onCompletion}method, {@code tryComplete()} can be replaced with {@link #propagateCompletion}.
{@code class ForEach ...}public void compute() // version 3 int l = lo, h = hi; while (h - l >= 2) { int mid = (l + h) >>> 1; addToPendingCount(1); new ForEach(this, array, op, mid, h).fork(); // right child h = mid; } if (h > l) op.apply(array[l]); propagateCompletion(); } } Additional improvements of such classes might entail precomputing pending counts so that they can be established in constructors, specializing classes for leaf steps, subdividing by say, four, instead of two per iteration, and using an adaptive threshold instead of always subdividing down to single elements.
Searching. A tree of CountedCompleters can search for a value or property in different parts of a data structure, and report a result in an {@link java.util.concurrent.atomic.AtomicReference AtomicReference} assoon as one is found. The others can poll the result to avoid unnecessary work. (You could additionally {@linkplain #cancel cancel} other tasks, but it is usually simpler and more efficientto just let them notice that the result is set and if so skip further processing.) Illustrating again with an array using full partitioning (again, in practice, leaf tasks will almost always process more than one element):
{@code}class Searcher extends CountedCompleter final E[] array; final AtomicReference result; final int lo, hi; Searcher(CountedCompleter p, E[] array, AtomicReference result, int lo, int hi) { super(p); this.array = array; this.result = result; this.lo = lo; this.hi = hi; } public E getRawResult() { return result.get(); } public void compute() { // similar to ForEach version 3 int l = lo, h = hi; while (result.get() == null && h >= l) { if (h - l >= 2) { int mid = (l + h) >>> 1; addToPendingCount(1); new Searcher(this, array, result, mid, h).fork(); h = mid; } else { E x = array[l]; if (matches(x) && result.compareAndSet(null, x)) quietlyCompleteRoot(); // root task is now joinable break; } } tryComplete(); // normally complete whether or not found } boolean matches(E e) { ... } // return true if found public static E search(E[] array) { return new Searcher(null, array, new AtomicReference(), 0, array.length).invoke(); } }} In this example, as well as others in which tasks have no other effects except to compareAndSet a common result, the trailing unconditional invocation of {@code tryComplete} could be madeconditional ( {@code if (result.get() == null) tryComplete();}) because no further bookkeeping is required to manage completions once the root task completes.
Recording subtasks. CountedCompleter tasks that combine results of multiple subtasks usually need to access these results in method {@link #onCompletion}. As illustrated in the following class (that performs a simplified form of map-reduce where mappings and reductions are all of type {@code E}), one way to do this in divide and conquer designs is to have each subtask record its sibling, so that it can be accessed in method {@code onCompletion}. This technique applies to reductions in which the order of combining left and right results does not matter; ordered reductions require explicit left/right designations. Variants of other streamlinings seen in the above examples may also apply.
{@code}class MyMapper E apply(E v) { ... } } class MyReducer { E apply(E x, E y) { ... } } class MapReducer extends CountedCompleter { final E[] array; final MyMapper mapper; final MyReducer reducer; final int lo, hi; MapReducer sibling; E result; MapReducer(CountedCompleter p, E[] array, MyMapper mapper, MyReducer reducer, int lo, int hi) { super(p); this.array = array; this.mapper = mapper; this.reducer = reducer; this.lo = lo; this.hi = hi; } public void compute() { if (hi - lo >= 2) { int mid = (lo + hi) >>> 1; MapReducer left = new MapReducer(this, array, mapper, reducer, lo, mid); MapReducer right = new MapReducer(this, array, mapper, reducer, mid, hi); left.sibling = right; right.sibling = left; setPendingCount(1); // only right is pending right.fork(); left.compute(); // directly execute left } else { if (hi > lo) result = mapper.apply(array[lo]); tryComplete(); } } public void onCompletion(CountedCompleter caller) { if (caller != this) { MapReducer child = (MapReducer)caller; MapReducer sib = child.sibling; if (sib == null || sib.result == null) result = child.result; else result = reducer.apply(child.result, sib.result); } } public E getRawResult() { return result; } public static E mapReduce(E[] array, MyMapper mapper, MyReducer reducer) { return new MapReducer(null, array, mapper, reducer, 0, array.length).invoke(); } }} Here, method {@code onCompletion} takes a form common to manycompletion designs that combine results. This callback-style method is triggered once per task, in either of the two different contexts in which the pending count is, or becomes, zero: (1) by a task itself, if its pending count is zero upon invocation of {@code tryComplete}, or (2) by any of its subtasks when they complete and decrement the pending count to zero. The {@code caller} argumentdistinguishes cases. Most often, when the caller is {@code this}, no action is necessary. Otherwise the caller argument can be used (usually via a cast) to supply a value (and/or links to other values) to be combined. Assuming proper use of pending counts, the actions inside {@code onCompletion} occur (once) upon completion ofa task and its subtasks. No additional synchronization is required within this method to ensure thread safety of accesses to fields of this task or other completed tasks.
Completion Traversals. If using {@code onCompletion} toprocess completions is inapplicable or inconvenient, you can use methods {@link #firstComplete} and {@link #nextComplete} to createcustom traversals. For example, to define a MapReducer that only splits out right-hand tasks in the form of the third ForEach example, the completions must cooperatively reduce along unexhausted subtask links, which can be done as follows:
{@code}class MapReducer extends CountedCompleter // version 2 final E[] array; final MyMapper mapper; final MyReducer reducer; final int lo, hi; MapReducer forks, next; // record subtask forks in list E result; MapReducer(CountedCompleter p, E[] array, MyMapper mapper, MyReducer reducer, int lo, int hi, MapReducer next) { super(p); this.array = array; this.mapper = mapper; this.reducer = reducer; this.lo = lo; this.hi = hi; this.next = next; } public void compute() { int l = lo, h = hi; while (h - l >= 2) { int mid = (l + h) >>> 1; addToPendingCount(1); (forks = new MapReducer(this, array, mapper, reducer, mid, h, forks)).fork; h = mid; } if (h > l) result = mapper.apply(array[l]); // process completions by reducing along and advancing subtask links for (CountedCompleter c = firstComplete(); c != null; c = c.nextComplete()) { for (MapReducer t = (MapReducer)c, s = t.forks; s != null; s = t.forks = s.next) t.result = reducer.apply(t.result, s.result); } } public E getRawResult() { return result; } public static E mapReduce(E[] array, MyMapper mapper, MyReducer reducer) { return new MapReducer(null, array, mapper, reducer, 0, array.length, null).invoke(); } }} Triggers. Some CountedCompleters are themselves never forked, but instead serve as bits of plumbing in other designs; including those in which the completion of one of more async tasks triggers another async task. For example:
{@code}class HeaderBuilder extends CountedCompleter<...> ... } class BodyBuilder extends CountedCompleter<...> { ... } class PacketSender extends CountedCompleter<...> { PacketSender(...) { super(null, 1); ... } // trigger on second completion public void compute() { } // never called public void onCompletion(CountedCompleter caller) { sendPacket(); } } // sample use: PacketSender p = new PacketSender(); new HeaderBuilder(p, ...).fork(); new BodyBuilder(p, ...).fork(); }
@since 1.8
@author Doug Lea