Adds a callback to Future that is invoked upon completion, whether success or failure.

corelib/src/implementation/future_implementation.dart

 // Copyright 2012 Google Inc. All Rights Reserved.
 // Dart core library.
 
 class FutureImpl<T> implements Future<T> {
 
   bool _isComplete = false;
 
   /**
    * Value that was provided to this Future by the Completer
    */
   T _value;
 
   /**
    * Exception that occured, if there was a problem providing
    * Value.
    */
   Object _exception;
 
   /**
    * true, if any onException handler handled the exception.
    */
   bool _exceptionHandled = false;
 
   /**
    * Listeners waiting to receive the value of this future.
    */
-  final List<Function> _listeners;
+  final List<Function> _successListeners;
 
   /**
    * Exception handlers waiting for exceptions.
    */
   final List<Function> _exceptionHandlers;
 
+  /**
+   * Listeners waiting to be called when the future completes.
+   */
+  final List<Function> _completionListeners;
+
   FutureImpl()
-    : _listeners = [],
-      _exceptionHandlers = [];
+    : _successListeners = [],
+      _exceptionHandlers = [],
+      _completionListeners = [];
 
   factory FutureImpl.immediate(T value) {
     final res = new FutureImpl();
     res._setValue(value);
     return res;
   }
 
   T get value() {
     if (!isComplete) {
       throw new FutureNotCompleteException();
@@ skipping 12 matching lines @@
   }
 
   bool get isComplete() {
     return _isComplete;
   }
 
   bool get hasValue() {
     return isComplete && _exception === null;
   }
 
-  void then(void onComplete(T value)) {
+  void then(void onSuccess(T value)) {
     if (hasValue) {
-      onComplete(value);
+      onSuccess(value);
     } else if (!isComplete) {
-      _listeners.add(onComplete);
+      _successListeners.add(onSuccess);
     } else if (!_exceptionHandled) {
       throw _exception;
     }
   }
 
   void handleException(bool onException(Object exception)) {
     if (_exceptionHandled) return;
     if (_isComplete) {
        if (_exception != null) {
          _exceptionHandled = onException(_exception);
        }
     } else {
       _exceptionHandlers.add(onException);
     }
   }
 
+  void onComplete(void complete(Future<T> future)) {
+    if (_isComplete) {
+      try {
+        complete(this);
+      } catch (final e) {}
+    } else {
+      _completionListeners.add(complete);
+    }
+  }
+
   void _complete() {
     _isComplete = true;
+
+    for (Function listener in _completionListeners) {

[Jennifer Messerly, 2012/06/04 20:11:17]

shouldn't this come after we run _exceptionHandlers and _successListeners, to
match try-catch-finally order?

[Bob Nystrom, 2012/06/04 20:20:40]

+1

[sam.mccall, 2012/06/04 21:35:57]

Yeah, that's probably less surprising. When e.g. a success listener throws, the
completion listeners will be interleaved between the success listener and the
corresponding catch block, but that's probably not a big deal.

+      try {
+        listener(this);
+      } catch (final e) {}
+    }
+
     if (_exception !== null) {
       for (Function handler in _exceptionHandlers) {
         // Explicitly check for true here so that if the handler returns null,
         // we don't get an exception in checked mode.
         if (handler(_exception) == true) {
           _exceptionHandled = true;
           break;
         }
       }
     }
 
     if (hasValue) {
-      for (Function listener in _listeners) {
+      for (Function listener in _successListeners) {
         listener(value);
       }
     } else {
-      if (!_exceptionHandled && _listeners.length > 0) {
+      if (!_exceptionHandled && _successListeners.length > 0) {
         throw _exception;
       }
     }
   }
 
   void _setValue(T value) {
     if (_isComplete) {
       throw new FutureAlreadyCompleteException();
     }
     _value = value;
     _complete();
   }
 
   void _setException(var exception) {
     if (exception === null) {
       // null is not a legal value for the exception of a Future
       throw new IllegalArgumentException(null);
     }
     if (_isComplete) {
       throw new FutureAlreadyCompleteException();
     }
     _exception = exception;
     _complete();
   }
 
   Future transform(Function transformation) {
     final completer = new Completer();
-    handleException((e) {
-      completer.completeException(e);
-      return true;
-    });
-    then((v) {
+    this.onComplete((f) {

[Jennifer Messerly, 2012/06/04 20:11:17]

do you need "this." here?

[sam.mccall, 2012/06/04 21:35:57]

Nope, oops

+      if (!f.hasValue) {
+        completer.completeException(f.exception);
+        return;
+      }
       var transformed = null;
       try {
-        transformed = transformation(v);
+        transformed = transformation(f.value);
       } catch (final e) {
         completer.completeException(e);
         return;
       }
       completer.complete(transformed);
     });
     return completer.future;
   }
 
   Future chain(Function transformation) {
     final completer = new Completer();
-    handleException((e) {
-      completer.completeException(e);
-      return true;
-    });
-    then((v) {
+    onComplete((f) {
+      if (!f.hasValue) {
+        completer.completeException(f.exception);
+        return;
+      }
       var future = null;
       try {
-        future = transformation(v);
+        future = transformation(f.value);
       } catch (final e) {
         completer.completeException(e);
         return;
       }
-      future.handleException((e) {
-        completer.completeException(e);
-        return true;
+      future.onComplete((g) {
+        if (g.hasValue) completer.complete(g.value);
+        else completer.completeException(g.exception);

[Jennifer Messerly, 2012/06/04 20:22:28]

This is interesting ... it almost suggests we should have a
Completer.completeFuture(Future f) method that does this logic? I wonder if
that'd be useful to anyone else, other than just to implement Future.chain.


style nit: we usually use curlies for if-else pairs.
See http://www.dartlang.org/articles/style-guide/
"DO use curly braces for all flow control structures."

The only exception IIRC is for single line ifs.

[sam.mccall, 2012/06/04 21:35:57]

Yeah, I can't see any obvious other uses, so I'm not inclined to add it now. It
does seem odd though...
(In Java I'd probably overload complete(T) and complete(Future<T>))
Oops, yes. This is probably better anyway:
future.onComplete((g) => g.hasValue
  ? completer.complete(g.value)
  : completer.completeException(g.exception));

[Jennifer Messerly, 2012/06/04 22:12:49]

sgtm

       });
-      future.then((b) => completer.complete(b));
     });
     return completer.future;
   }
 }
 
 class CompleterImpl<T> implements Completer<T> {
 
   final FutureImpl<T> _futureImpl;
 
   CompleterImpl() : _futureImpl = new FutureImpl() {}
 
   Future<T> get future() {
     return _futureImpl;
   }
 
   void complete(T value) {
     _futureImpl._setValue(value);
   }
 
   void completeException(var exception) {
     _futureImpl._setException(exception);
   }
 }