Add a new public API to group Deferreds and preserve their order.

Author: tsuna

NEWS

@@ -1,5 +1,12 @@
 The SUAsync Library - User visible changes.
 
+* Version 1.4.0 (2013-??-??) [???????]
+
+New public APIs:
+  - `groupInOrder(Collection)' was added to provide an alternative to
+    `group(...)' that preserves the order of the results.
+
+
 * Version 1.3.3 (2013-06-16) [fc509ea]
 
 Noteworthy changes:

src/Deferred.java

@@ -889,11 +889,28 @@ public String toString() {
    * <p>
    * There's no guarantee on the order of the results in the deferred list
    * returned, it depends on the order in which the {@code Deferred}s in the
-   * group complete.
+   * group complete.  If you want to preserve the order, use
+   * {@link #groupInOrder(Collection)} instead.
    */
   public static <T>
     Deferred<ArrayList<T>> group(final Collection<Deferred<T>> deferreds) {
-    return new DeferredGroup<T>(deferreds).getDeferred();
+    return new DeferredGroup<T>(deferreds, false).getDeferred();
+  }
+
+  /**
+   * Groups multiple {@code Deferred}s together in a single one.
+   * <p>
+   * This is the same thing as {@link #group(Collection)} except that we
+   * guarantee we preserve the order of the {@code Deferred}s.
+   * @param deferreds All the {@code Deferred}s to group together.
+   * @return A new {@code Deferred} that will be called back once all the
+   * {@code Deferred}s given in argument have been called back.
+   * @see #group(Collection)
+   * @since 1.4
+   */
+  public static <T>
+    Deferred<ArrayList<T>> groupInOrder(final Collection<Deferred<T>> deferreds) {
+    return new DeferredGroup<T>(deferreds, true).getDeferred();
   }
 
   /**
@@ -915,7 +932,7 @@ Deferred<ArrayList<T>> group(final Deferred<T> d1, final Deferred<T> d2) {
     final ArrayList<Deferred<T>> tmp = new ArrayList<Deferred<T>>(2);
     tmp.add(d1);
     tmp.add(d2);
-    return new DeferredGroup<T>(tmp).getDeferred();
+    return new DeferredGroup<T>(tmp, false).getDeferred();
   }
 
   /**
@@ -941,7 +958,7 @@ Deferred<ArrayList<T>> group(final Deferred<T> d1,
     tmp.add(d1);
     tmp.add(d2);
     tmp.add(d3);
-    return new DeferredGroup<T>(tmp).getDeferred();
+    return new DeferredGroup<T>(tmp, false).getDeferred();
   }
 
   /**

src/DeferredGroup.java

@@ -41,8 +41,11 @@ final class DeferredGroup<T> {
    */
   private final Deferred<ArrayList<T>> parent = new Deferred<ArrayList<T>>();
 
-  /** How many results do we expect?  */
-  private final int nresults;
+  /**
+   * How many results do we expect?.
+   * Need to acquires this' monitor before changing.
+   */
+  private int nresults;
 
   /**
    * All the results for each Deferred we're grouping.
@@ -54,8 +57,17 @@ final class DeferredGroup<T> {
   /**
    * Constructor.
    * @param deferreds All the {@link Deferred}s we want to group.
+   * @param ordered If true, the results will be presented in the same order
+   * as the {@link Deferred}s are in the {@code deferreds} argument.
+   * If false, results will be presented in the order in which they arrive.
+   * In other words, assuming that {@code deferreds} is a list of three
+   * {@link Deferred} objects {@code [A, B, C]}, then if {@code ordered} is
+   * true, {@code results} will be {@code [result A, result B, result C]}
+   * whereas if {@code ordered} is false then the order in {@code results}
+   * is determined by the order in which callbacks fire on A, B, and C.
    */
-  public DeferredGroup(final Collection<Deferred<T>> deferreds) {
+  public DeferredGroup(final Collection<Deferred<T>> deferreds,
+                       final boolean ordered) {
     nresults = deferreds.size();
     results = new ArrayList<Object>(nresults);
 
@@ -64,6 +76,7 @@ public DeferredGroup(final Collection<Deferred<T>> deferreds) {
       return;
     }
 
+    // Callback used to collect results in the order in which they appear.
     final class Notify<T> implements Callback<T, T> {
       public T call(final T arg) {
         recordCompletion(arg);
@@ -74,10 +87,37 @@ public String toString() {
       }
     };
 
-    final Notify<T> notify = new Notify<T>();
+    // Callback that preserves the original orders of the Deferreds.
+    final class NotifyOrdered<T> implements Callback<T, T> {
+      private final int index;
+      NotifyOrdered(int index) {
+        this.index = index;
+      }
+      public T call(final T arg) {
+        recordCompletion(arg, index);
+        return arg;
+      }
+      public String toString() {
+        return "notify #" + index + " DeferredGroup@"
+          + DeferredGroup.super.hashCode();
+      }
+    };
 
-    for (final Deferred<T> d : deferreds) {
-      d.addBoth(notify);
+    if (ordered) {
+      int i = 0;
+      for (final Deferred<T> d : deferreds) {
+        results.add(null);  // ensures results.set(i, result) is valid.
+        // Note: it's important to add the callback after the line above,
+        // as the callback can fire at any time once it's been added, and
+        // if it fires before results.set(i, result) is valid, we'll get
+        // an IndexOutOfBoundsException.
+        d.addBoth(new NotifyOrdered<T>(i++));
+      }
+    } else {
+      final Notify<T> notify = new Notify<T>();
+      for (final Deferred<T> d : deferreds) {
+        d.addBoth(notify);
+      }
     }
   }
 
@@ -93,30 +133,50 @@ public Deferred<ArrayList<T>> getDeferred() {
    * @param result The result of the deferred.
    */
   private void recordCompletion(final Object result) {
-    int size;
+    int left;
     synchronized (this) {
       results.add(result);
-      size = results.size();
+      left = --nresults;
+    }
+    if (left == 0) {
+      done();
     }
-    if (size == nresults) {
-      // From this point on, we no longer need to synchronize in order to
-      // access `results' since we know we're done, so no other thread is
-      // going to call this method on this instance again.
-      for (final Object r : results) {
-        if (r instanceof Exception) {
-          parent.callback(new DeferredGroupException(results, (Exception) r));
-          return;
-        }
+  }
+
+  /**
+   * Called back when one of the {@link Deferred} in the group completes.
+   * @param result The result of the deferred.
+   * @param index The index of the result.
+   */
+  private void recordCompletion(final Object result, final int index) {
+    int left;
+    synchronized (this) {
+      results.set(index, result);
+      left = --nresults;
+    }
+    if (left == 0) {
+      done();
+    }
+  }
+
+  /** Called once we have obtained all the results of this group.  */
+  private void done() {
+    // From this point on, we no longer need to synchronize in order to
+    // access `results' since we know we're done, so no other thread is
+    // going to call recordCompletion() again.
+    for (final Object r : results) {
+      if (r instanceof Exception) {
+        parent.callback(new DeferredGroupException(results, (Exception) r));
+        return;
       }
-      parent.callback(results);
     }
+    parent.callback(results);
   }
 
   public String toString() {
     return "DeferredGroup"
       + "(parent=" + parent
-      + ", # results=" + results.size() + " / " + nresults
-      + ')';
+      + ", # results=" + results.size() + " / " + nresults + " left)";
   }
 
 }