Make Completers asynchronous.

sdk/lib/async/future.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.async;
 
 /**
  * A [Future] represents a delayed computation. It is used to obtain a not-yet
  * available value, or error, sometime in the future.  Receivers of a
  * [Future] can register callbacks that handle the value or error once it is
@@ skipping 325 matching lines @@
  *     // later when value is available, call:
  *     completer.complete(value);
  *
  *     // alternatively, if the service cannot produce the value, it
  *     // can provide an error:
  *     completer.completeError(error);
  *
  */
 abstract class Completer<T> {
 
-  factory Completer() => new _CompleterImpl<T>();
+  factory Completer() => new _AsyncCompleter<T>();
+
+  /**
+   * Completes the future synchronously.
+   *
+   * This constructor should be avoided unless the completion of the future is
+   * known to be the final result of another asynchronous operation. If in doubt
+   * use the default [Completer] constructor.
+   *
+   * Example:
+   *
+   *     var completer = new Completer.sync();
+   *     // The completion is the result of the asynchronous onDone event.
+   *     // No other operation is performed after the completion. It is safe
+   *     // to use the Completer.sync constructor.
+   *     stream.listen(print, onDone: () { completer.complete("done"); });
+   *
+   * Bad example. Do not use this code. Only for illustrative purposes:
+   *
+   *     var completer = new Completer.sync();
+   *     // The completion is the result of the asynchronous onDone event.
+   *     // However, there is still code executed after the completion. This
+   *     // operation is *not* safe.
+   *     stream.listen(print, onDone: () {
+   *       completer.complete("done");
+   *       foo();  // This operation follows the completion.
+   *     });
+   *
+   * *WARNING* This constructor is experimental and could disappear or change
+   * behavior.
+   */
+  factory Completer.sync() => new _SyncCompleter<T>();
 
   /** The future that will contain the result provided to this completer. */
   Future get future;
 
   /**
    * Completes [future] with the supplied values.
    *
    * All listeners on the future will be immediately informed about the value.
    */
   void complete([T value]);
 
   /**
    * Complete [future] with an error.
    *
    * Completing a future with an error indicates that an exception was thrown
    * while trying to produce a value.
    *
    * The argument [exception] should not be `null`.
    */
   void completeError(Object exception, [Object stackTrace]);
 
   /**
    * Whether the future has been completed.
    */
   bool get isCompleted;
 }