Refactor Future constructors.

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 66 matching lines @@
  * Similar to the synchronous code, the error handler (registered with
  * [catchError]) is handling the errors for exceptions coming from calls to
  * 'foo', as well as 'bar'. This would not be the case if the error-handler was
  * registered at the same time as the value-handler.
  *
  * Futures can have more than one callback-pairs registered. Each successor is
  * treated independently and is handled as if it was the only successor.
  */
 // TODO(floitsch): document chaining.
 abstract class Future<T> {
+
   /**
-   * Creates a future containing the result of calling [function].
+   * Creates a future containing the result of calling [computation]
+   * asynchronously with [runAsync].
    *
-   * The result of computing [:function():] is either a returned value or
-   * a throw.
-   *
-   * If a value is returned, it becomes the result of the created future.
-   *
-   * If calling [function] throws, the created [Future] will be completed
-   * with an async error containing the thrown value and a captured
-   * stacktrace.
-   *
-   * However, if the result of calling [function] is already an asynchronous
-   * result, we treat it specially.
+   * if the result of executing [computation] throws, the returned future is
+   * completed with the error. If a thrown value is an [AsyncError], it is used
+   * directly, instead of wrapping this error again in another [AsyncError].
    *
    * If the returned value is itself a [Future], completion of
    * the created future will wait until the returned future completes,
    * and will then complete with the same result.
    *
-   * If a thrown value is an [AsyncError], it is used directly as the result
-   * of the created future.
+   * If a value is returned, it becomes the result of the created future.
    */
-  factory Future.of(function()) {
+  factory Future(computation()) {
+    _ThenFuture<dynamic, T> future =
+        new _ThenFuture<dynamic, T>((_) => computation());

[Lasse Reichstein Nielsen, 2013/04/15 10:27:46]

I'd prefer using _FutureImpl directly instead of _ThenFuture, but I can see this
is shorter.

[floitsch, 2013/04/15 20:30:11]

Falls under "optimizations for later" category.

+    runAsync(() => future._sendValue(null));
+    return future;
+  }
+
+  /**
+   * Creates a future containing the result of immediately calling
+   * [computation].
+   *
+   * if the result of executing [computation] throws, the returned future is
+   * completed with the error. If a thrown value is an [AsyncError], it is used
+   * directly, instead of wrapping this error again in another [AsyncError].
+   *
+   * If the returned value is itself a [Future], completion of
+   * the created future will wait until the returned future completes,
+   * and will then complete with the same result.
+   *
+   * If a value is returned, it becomes the result of the created future.
+   */
+  factory Future.sync(computation()) {

[Lasse Reichstein Nielsen, 2013/04/15 10:27:46]

I prefer Future.of.
The "sync" name (apart from being an abbreviation) isn't obvious. Nor is "of",
on the other hand, it's so bland it can mean anything.
So I guess it's down to: I don't like "sync"!

[floitsch, 2013/04/15 20:30:11]

A lot of users got this confused and thought that "of" would by asynchronous. At
least "sync" makes it really clear.

     try {
-      var result = function();
+      var result = computation();
       return new _FutureImpl<T>().._setOrChainValue(result);
     } catch (error, stackTrace) {
       return new _FutureImpl<T>.immediateError(error, stackTrace);
     }
   }
 
   /**
    * A future whose value is available in the next event-loop iteration.
    *
    * If [value] is not a [Future], using this constructor is equivalent
-   * to [:new Future.of(() => value):].
+   * to [:new Future.sync(() => value):].
    *
    * See [Completer] to create a Future and complete it later.
    */
-  factory Future.immediate(T value) => new _FutureImpl<T>.immediate(value);
+  factory Future.value([T value]) => new _FutureImpl<T>.immediate(value);
 
   /**
    * A future that completes with an error in the next event-loop iteration.

[Anders Johnsen, 2013/04/15 08:59:06]

Write it's the same as new Future(() => throw new AsyncError(error,
stackTrace));?

[Lasse Reichstein Nielsen, 2013/04/15 10:27:46]

I hope not. You should never throw an AsyncError (but I guess we have accepted
it in places as a kind of rethrow).

[floitsch, 2013/04/15 20:30:11]

AsyncError is gone.

    *
    * See [Completer] to create a Future and complete it later.
    */
-  factory Future.immediateError(var error, [Object stackTrace]) {
+  factory Future.error(var error, [Object stackTrace]) {
     return new _FutureImpl<T>.immediateError(error, stackTrace);
   }
 
   /**
    * Creates a future that completes after a delay.
    *
    * The future will be completed after the given [duration] has passed with
    * the result of calling [computation]. If the duration is 0 or less, it
    * completes no sooner than in the next event-loop iteration.
    *
@@ skipping 36 matching lines @@
    * completes when all elements have been processed.
    *
    * The return values of all [Future]s are discarded. Any errors will cause the
    * iteration to stop and will be piped through the returned [Future].
    */
   static Future forEach(Iterable input, Future f(element)) {
     _FutureImpl doneSignal = new _FutureImpl();
     Iterator iterator = input.iterator;
     void nextElement(_) {
       if (iterator.moveNext()) {
-        new Future.of(() => f(iterator.current))
+        new Future.sync(() => f(iterator.current))
             .then(nextElement, onError: doneSignal._setError);
       } else {
         doneSignal._setValue(null);
       }
     }
     nextElement(null);
     return doneSignal;
   }
 
   /**
@@ skipping 158 matching lines @@
    * Otherwise the [exception] and an optional [stackTrace] is combined into an
    * [AsyncError] and sent to this future's listeners.
    */
   void completeError(Object exception, [Object stackTrace]);
 
   /**
    * Whether the future has been completed.
    */
   bool get isCompleted;
 }