ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/test/loops/BinaryAsyncAction.java
(Generate patch)

Comparing jsr166/src/test/loops/BinaryAsyncAction.java (file contents):
Revision 1.4 by jsr166, Sat Jan 28 04:40:12 2012 UTC vs.
Revision 1.14 by jsr166, Mon Nov 26 11:47:41 2012 UTC

# Line 1 | Line 1
1   /*
2   * Written by Doug Lea with assistance from members of JCP JSR-166
3   * Expert Group and released to the public domain, as explained at
4 < *
4 > * http://creativecommons.org/publicdomain/zero/1.0/
5   */
6  
7   import java.util.concurrent.*;
# Line 15 | Line 15 | import java.util.concurrent.atomic.*;
15   * BinaryAsyncActions are simpler to use and have less overhead in
16   * typical uasges but are restricted to binary computation trees.
17   *
18 < * <p> Upon construction, an BinaryAsyncAction does not bear any
18 > * <p>Upon construction, a BinaryAsyncAction does not bear any
19   * linkages. For non-root tasks, links must be established using
20 < * method <tt>linkSubtasks</tt> before use.
20 > * method {@link #linkSubtasks} before use.
21   *
22 < * <p> <b>Sample Usage.</b>  A version of Fibonacci:
22 > * <p><b>Sample Usage.</b>  A version of Fibonacci:
23   * <pre>
24   * class Fib extends BinaryAsyncAction {
25   *   final int n;
# Line 27 | Line 27 | import java.util.concurrent.atomic.*;
27   *   Fib(int n) { this.n = n; }
28   *   protected void compute() {
29   *     if (n &gt; 1) {
30 < *        linkAndForkSubtasks(new Fib(n-1), new Fib(n-2));
30 > *       linkAndForkSubtasks(new Fib(n-1), new Fib(n-2));
31   *     else {
32 < *        result = n; // fib(0)==0; fib(1)==1
33 < *        complete();
32 > *       result = n; // fib(0)==0; fib(1)==1
33 > *       complete();
34   *     }
35   *   }
36   *   protected void onComplete(BinaryAsyncAction x, BinaryAsyncAction y) {
37 < *      result = ((Fib)x).result + ((Fib)y).result;
37 > *     result = ((Fib)x).result + ((Fib)y).result;
38   *   }
39   * }
40   * </pre>
41 < * An alternative, and usually faster strategy is to instead use a
41 > * An alternative, and usually faster, strategy is to instead use a
42   * loop to fork subtasks:
43   * <pre>
44   *   protected void compute() {
45   *     Fib f = this;
46   *     while (f.n &gt; 1) {
47 < *        Fib left = new Fib(f.n - 1);
48 < *        Fib right = new Fib(f.n - 2);
49 < *        f.linkSubtasks(left, right);
50 < *        right.fork(); // fork right
51 < *        f = left;     // loop on left
47 > *       Fib left = new Fib(f.n - 1);
48 > *       Fib right = new Fib(f.n - 2);
49 > *       f.linkSubtasks(left, right);
50 > *       right.fork(); // fork right
51 > *       f = left;     // loop on left
52   *     }
53   *     f.result = f.n;
54   *     f.complete();
# Line 75 | Line 75 | public abstract class BinaryAsyncAction
75  
76      /**
77       * Creates a new action. Unless this is a root task, you will need
78 <     * to link it using method <tt>linkSubtasks</tt> before forking as
78 >     * to link it using method {@link #linkSubtasks} before forking as
79       * a subtask.
80       */
81      protected BinaryAsyncAction() {
# Line 89 | Line 89 | public abstract class BinaryAsyncAction
89       * as parent, and each other as siblings.
90       * @param x one subtask
91       * @param y the other subtask
92 <     * @throws NullPointerException if either argument is null.
92 >     * @throws NullPointerException if either argument is null
93       */
94      public final void linkSubtasks(BinaryAsyncAction x, BinaryAsyncAction y) {
95          x.parent = y.parent = this;
# Line 98 | Line 98 | public abstract class BinaryAsyncAction
98      }
99  
100      /**
101 <     * Overridable callback action triggered upon <tt>complete</tt> of
101 >     * Overridable callback action triggered upon {@code complete} of
102       * subtasks.  Upon invocation, both subtasks have completed.
103 <     * After return, this task <tt>isDone</tt> and is joinable by
104 <     * other tasks. The default version of this method does
105 <     * nothing. But it may be overridden in subclasses to perform
106 <     * some action (for example a reduction) when this task is
107 <     * completes.
103 >     * After return, this task {@code isDone} and is joinable by
104 >     * other tasks. The default version of this method does nothing.
105 >     * But it may be overridden in subclasses to perform some action
106 >     * (for example a reduction) when this task is completes.
107       * @param x one subtask
108       * @param y the other subtask
109       */
# Line 113 | Line 112 | public abstract class BinaryAsyncAction
112  
113      /**
114       * Overridable callback action triggered by
115 <     * <tt>completeExceptionally</tt>.  Upon invocation, this task has
115 >     * {@code completeExceptionally}.  Upon invocation, this task has
116       * aborted due to an exception (accessible via
117 <     * <tt>getException</tt>). If this method returns <tt>true</tt>,
117 >     * {@code getException}). If this method returns {@code true},
118       * the exception propagates to the current task's
119       * parent. Otherwise, normal completion is propagated.  The
120       * default version of this method does nothing and returns
121 <     * <tt>true</tt>.
121 >     * {@code true}.
122       * @return true if this task's exception should be propagated to
123 <     * this tasks parent.
123 >     * this task's parent.
124       */
125      protected boolean onException() {
126          return true;
127      }
128  
129      /**
130 <     * Equivalent in effect to invoking <tt>linkSubtasks</tt> and then
130 >     * Equivalent in effect to invoking {@link #linkSubtasks} and then
131       * forking both tasks.
132       * @param x one subtask
133       * @param y the other subtask
# Line 157 | Line 156 | public abstract class BinaryAsyncAction
156  
157      /**
158       * Completes this task, and if this task has a sibling that is
159 <     * also complete, invokes <tt>onComplete</tt> of parent task, and so
159 >     * also complete, invokes {@code onComplete} of parent task, and so
160       * on. If an exception is encountered, tasks instead
161 <     * <tt>completeExceptionally</tt>.
161 >     * {@code completeExceptionally}.
162       */
163      public final void complete() {
164          // todo: Use tryUnfork without possibly blowing stack
# Line 185 | Line 184 | public abstract class BinaryAsyncAction
184      /**
185       * Completes this task abnormally. Unless this task already
186       * cancelled or aborted, upon invocation, this method invokes
187 <     * <tt>onException</tt>, and then, depending on its return value,
188 <     * completees parent (if one exists) exceptionally or normally.  To
187 >     * {@code onException}, and then, depending on its return value,
188 >     * completes parent (if one exists) exceptionally or normally.  To
189       * avoid unbounded exception loops, this method aborts if an
190 <     * exception is encountered in any <tt>onException</tt>
190 >     * exception is encountered in any {@code onException}
191       * invocation.
192       * @param ex the exception to throw when joining this task
193       * @throws NullPointerException if ex is null
194       * @throws Throwable if any invocation of
195 <     * <tt>onException</tt> does so.
195 >     * {@code onException} does so
196       */
197      public final void completeExceptionally(Throwable ex) {
198          BinaryAsyncAction a = this;
# Line 210 | Line 209 | public abstract class BinaryAsyncAction
209      /**
210       * Returns this task's parent, or null if none or this task
211       * is already complete.
212 <     * @return this task's parent, or null if none.
212 >     * @return this task's parent, or null if none
213       */
214      public final BinaryAsyncAction getParent() {
215          return parent;
# Line 219 | Line 218 | public abstract class BinaryAsyncAction
218      /**
219       * Returns this task's sibling, or null if none or this task is
220       * already complete.
221 <     * @return this task's sibling, or null if none.
221 >     * @return this task's sibling, or null if none
222       */
223      public BinaryAsyncAction getSibling() {
224          return sibling;
# Line 268 | Line 267 | public abstract class BinaryAsyncAction
267      }
268  
269      /**
270 <     * Sets the control state to the given value,
270 >     * Increments the control state.
271       * @param value the new value
272       */
273      protected final void incrementControlState() {
# Line 276 | Line 275 | public abstract class BinaryAsyncAction
275      }
276  
277      /**
278 <     * Decrement the control state
278 >     * Decrements the control state.
279       * @return true if successful
280       */
281      protected final void decrementControlState() {

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines