Change and documentat how completer handles futures.

sdk/lib/async/future_impl.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;
 
 /** The onValue and onError handlers return either a value or a future */
 typedef dynamic _FutureOnValue<T>(T value);
 /** Test used by [Future.catchError] to handle skip some errors. */
 typedef bool _FutureErrorTest(var error);
 /** Used by [WhenFuture]. */
 typedef _FutureAction();
 
 abstract class _Completer<T> implements Completer<T> {
   final _Future<T> future = new _Future<T>();
 
-  void complete([T value]);
+  void complete([value]);
 
   void completeError(Object error, [StackTrace stackTrace]);
 
   // The future's _isComplete doesn't take into account pending completions.
   // We therefore use _mayComplete.
   bool get isCompleted => !future._mayComplete;
 }
 
 class _AsyncCompleter<T> extends _Completer<T> {
 
-  void complete([T value]) {
+  void complete([value]) {
     if (!future._mayComplete) throw new StateError("Future already completed");
     future._asyncComplete(value);
   }
 
   void completeError(Object error, [StackTrace stackTrace]) {
+    if (error is Future) {

[floitsch, 2013/10/29 18:13:35]

ditto. I don't think this restriction is necessary.

[Lasse Reichstein Nielsen, 2013/10/30 09:22:17]

Removing.

+      throw new ArgumentError("Cannot use completeError with a future - "
+                              "use complete instead");
+    }
+    if (error == null) throw new ArgumentError("Error must not be null");
     if (!future._mayComplete) throw new StateError("Future already completed");
     future._asyncCompleteError(error, stackTrace);
   }
 }
 
 class _SyncCompleter<T> extends _Completer<T> {
 
-  void complete([T value]) {
+  void complete([value]) {
     if (!future._mayComplete) throw new StateError("Future already completed");
     future._complete(value);
   }
 
   void completeError(Object error, [StackTrace stackTrace]) {
+    if (error is Future) {

[floitsch, 2013/10/29 18:13:35]

ditto

[Lasse Reichstein Nielsen, 2013/10/30 09:22:17]

ditto too.

+      throw new ArgumentError("Cannot use completeError with a future. "
+                              "Use complete instead.");
+    }
     if (!future._mayComplete) throw new StateError("Future already completed");
     future._completeError(error, stackTrace);
   }
 }
 
 class _Future<T> implements Future<T> {
   // State of the future. The state determines the interpretation of the
   // [resultOrListeners] field.
   // TODO(lrn): rename field since it can also contain a chained future.
 
@@ skipping 167 matching lines @@
   }
 
   void _setError(Object error, StackTrace stackTrace) {
     assert(!_isComplete);  // But may have a completion pending.
     _state = _ERROR;
     _resultOrListeners = new _AsyncError(error, stackTrace);
   }
 
   void _addListener(_Future listener) {
     assert(listener._nextListener == null);
+    _Future target = this;

[floitsch, 2013/10/29 18:13:35]

spurious change?

[Lasse Reichstein Nielsen, 2013/10/30 09:22:17]

ack, yes. Left over from debugging.
Removed.

     if (_isComplete) {
       // Handle late listeners asynchronously.
       _zone.scheduleMicrotask(() {
         _propagateToListeners(this, listener);
       });
     } else {
       listener._nextListener = _resultOrListeners;
       _resultOrListeners = listener;
     }
   }
@@ skipping 63 matching lines @@
     assert(_onValue == null);
     assert(_onError == null);
     assert(_whenCompleteAction == null);
     assert(_errorTest == null);
 
     if (stackTrace != null) {
       // Force the stack trace onto the error, even if it already had one.
       _attachStackTrace(error, stackTrace);
     }
 
-    _Future listeners = _isChained ? null : _removeListeners();
+    _Future listeners = _removeListeners();
     _setError(error, stackTrace);
     _propagateToListeners(this, listeners);
   }
 
   void _asyncComplete(value) {
     assert(!_isComplete);
     assert(_onValue == null);
     assert(_onError == null);
     assert(_whenCompleteAction == null);
     assert(_errorTest == null);
@@ skipping 207 matching lines @@
       } else {
         listeners = listener._removeListeners();
         _AsyncError asyncError = listenerValueOrError;
         listener._setError(asyncError.error, asyncError.stackTrace);
       }
       // Prepare for next round.
       source = listener;
     }
   }
 }