Allow optional callStack argument to Future.completeException().

corelib/src/future.dart

 // Copyright (c) 2011, 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.
 
-// Dart core library.
-
-
 /**
  * A [Future] is used to obtain a value sometime in the future.  Receivers of a
- * [Future] can obtain the value by passing a callback to [then].
- * For example:
+ * [Future] can obtain the value by passing a callback to [then]. For example:
  *
- *   Future<int> future = getFutureFromSomewhere();
- *   future.then((value) {
- *     print("I received the number $value");
- *   });
- * 
+ *     Future<int> future = getFutureFromSomewhere();
+ *     future.then((value) {
+ *       print("I received the number $value");
+ *     });
+ *
  * A future may complete by *succeeding* (producing a value) or *failing*
  * (producing an exception, which may be handled with [handleException]).
  * Callbacks passed to [onComplete] will be invoked in either case.
  *
  * When a future completes, the following actions happen in order:
  *
  *   1. if the future suceeded, handlers registered with [then] are called.
  *   2. if the future failed, handlers registered with [handleException] are
  *      called in sequence, until one returns true.
  *   3. handlers registered with [onComplete] are called
@@ skipping 12 matching lines @@
   T get value();
 
   /**
    * Exception that occurred ([:null:] if no exception occured). This property
    * throws a [FutureNotCompleteException] if it is used before this future is
    * completes.
    */
   Object get exception();
 
   /**
+   * The call stack object associated with the exception that occurred. This
+   * throws a [FutureNotCompleteException] if it is used before the future
+   * completes. Returns [:null:] if the future completed successfully or a
+   * call stack wasn't provided with the exception when it occurred.
+   */
+  Object get callStack();

[Siggi Cherem (dart-lang), 2012/06/12 18:38:25]

callStack => stackTrace?

+
+  /**
    * Whether the future is complete (either the value is available or there was
    * an exception).
    */
   bool get isComplete();
 
   /**
    * Whether the value is available (meaning [isComplete] is true, and there was
    * no exception).
    */
   bool get hasValue();
@@ skipping 30 matching lines @@
   void handleException(bool onException(Object exception));
 
   /**
    * A future representing [transformation] applied to this future's value.
    *
    * When this future gets a value, [transformation] will be called on the
    * value, and the returned future will receive the result.
    *
    * If an exception occurs (received by this future, or thrown by
    * [transformation]) then the returned future will receive the exception.
-   *  
-   * You must not add exception handlers to [this] future prior to calling 
+   *
+   * You must not add exception handlers to [this] future prior to calling
    * transform, and any you add afterwards will not be invoked.
    */
   Future transform(transformation(T value));
 
    /**
     * A future representing an asynchronous transformation applied to this
     * future's value. [transformation] must return a Future.
     *
     * When this future gets a value, [transformation] will be called on the
     * value. When the resulting future gets a value, the returned future
     * will receive it.
     *
     * If an exception occurs (received by this future, thrown by
     * [transformation], or received by the future returned by [transformation])
     * then the returned future will receive the exception.
     *
-    * You must not add exception handlers to [this] future prior to calling 
+    * You must not add exception handlers to [this] future prior to calling
     * chain, and any you add afterwards will not be invoked.
     */
    Future chain(Future transformation(T value));
 }
 
 
 /**
  * A [Completer] is used to produce [Future]s and supply their value when it
  * becomes available.
  *
@@ skipping 18 matching lines @@
   Completer();
 
   /** The future that will contain the value produced by this completer. */
   Future get future();
 
   /** Supply a value for [future]. */
   void complete(T value);
 
   /**
    * Indicate in [future] that an exception occured while trying to produce its
-   * value. The argument [exception] should not be [:null:].
+   * value. The argument [exception] should not be [:null:]. A [callStack]
+   * object can be provided as well to give the user information about where
+   * the error occurred. If omitted, it will be [:null:].
    */
-  void completeException(Object exception);
+  void completeException(Object exception, [Object callStack]);
 }
 
 /** Thrown when reading a future's properties before it is complete. */
 class FutureNotCompleteException implements Exception {
   FutureNotCompleteException() {}
   String toString() => "Exception: future has not been completed";
 }
 
 /**
  * Thrown if a completer tries to set the value on a future that is already
@@ skipping 41 matching lines @@
         }
       });
       future.handleException((exception) {
         if (!result.isComplete) completer.completeException(exception);
         return true;
       });
     }
     return result;
   }
 }