Allow optional callStack argument to Future.completeException().

corelib/src/future.dart

Index: corelib/src/future.dart
diff --git a/corelib/src/future.dart b/corelib/src/future.dart
index 30a4d40c039b72084be775858c4f6e33ddc805de..cbb15a59f0ec690b1991c3f8060a78b901c2debc 100644
--- a/corelib/src/future.dart
+++ b/corelib/src/future.dart
@@ -2,19 +2,15 @@
 // 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.
@@ -47,6 +43,14 @@ interface Future<T> default FutureImpl<T> {
   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).
    */
@@ -97,8 +101,8 @@ interface Future<T> default FutureImpl<T> {
    *
    * 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));
@@ -115,7 +119,7 @@ interface Future<T> default FutureImpl<T> {
     * [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));
@@ -154,9 +158,11 @@ interface Completer<T> default CompleterImpl<T> {
 
   /**
    * 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. */