Make Completers asynchronous.

sdk/lib/async/future.dart

Index: sdk/lib/async/future.dart
diff --git a/sdk/lib/async/future.dart b/sdk/lib/async/future.dart
index 7219719d944f713d878d11e54f0748016c9df709..53f81a2330d42bf157daa3da1dc9e9fee3121e94 100644
--- a/sdk/lib/async/future.dart
+++ b/sdk/lib/async/future.dart
@@ -345,6 +345,37 @@ abstract class Completer<T> {
 
   factory Completer() => new _CompleterImpl<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 synchronous operation. If in doubt

[Lasse Reichstein Nielsen, 2013/05/06 06:49:11]

synchronous -> asynchronous? (following the first example).

[floitsch, 2013/05/06 15:14:45]

Done.

+   * 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 _SyncCompleterImpl<T>();
+
   /** The future that will contain the result provided to this completer. */
   Future get future;