Add runAsync interceptor.

sdk/lib/async/zone.dart

 // Copyright (c) 2013, 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 Zone represents the asynchronous version of a dynamic extent. Asynchronous
  * callbacks are executed in the zone they have been queued in. For example,
  * the callback of a `future.then` is executed in the same zone as the one where
@@ skipping 20 matching lines @@
    *
    * The main purpose of this method is to allow `this` to attach debugging
    * information to the returned zone.
    */
   _Zone fork();
 
   /**
    * Tells the zone that it needs to wait for one more callback before it is
    * done.
    *
-   * Use [executeCallback] or [cancelCallbackExpectation] when the callback is executed
-   * (or canceled).
+   * Use [executeCallback] or [cancelCallbackExpectation] when the callback is
+   * executed (or canceled).
    */
   void expectCallback();
 
   /**
    * Tells the zone not to wait for a callback anymore.
    *
    * Prefer calling [executeCallback], instead. This method is mostly useful
    * for repeated callbacks (for example with [Timer.periodic]). In this case
    * one should should call [expectCallback] when the repeated callback is
    * initiated, and [cancelCallbackExpectation] when the [Timer] is canceled.
    */
   void cancelCallbackExpectation();
 
   /**
-   * Executes the given callback in this zone.
+   * Executes the given callback [f] in this zone.
    *
    * Decrements the number of callbacks this zone is waiting for (see
    * [expectCallback]).
    */
-  void executeCallback(void fun());
+  void executeCallback(void f());
 
   /**
    * Same as [executeCallback] but catches uncaught errors and gives them to
    * [handleUncaughtError].
    */
-  void executeCallbackGuarded(void fun());
+  void executeCallbackGuarded(void f());
 
   /**
    * Same as [executeCallback] but does not decrement the number of
    * callbacks this zone is waiting for (see [expectCallback]).
    */
-  void executePeriodicCallback(void fun());
+  void executePeriodicCallback(void f());
 
   /**
    * Same as [executePeriodicCallback] but catches uncaught errors and gives
    * them to [handleUncaughtError].
    */
-  void executePeriodicCallbackGuarded(void fun());
+  void executePeriodicCallbackGuarded(void f());
 
   /**
-   * Runs [fun] asynchronously in this zone.
+   * Executes [f] in `this` zone.
+   *
+   * The behavior of this method should be the same as
+   * [executePeriodicCallback] except that it can have a return value.
+   *
+   * Returns the result of the invocation.
    */
-  void runAsync(void fun());
+  runFromChildZone(f());
+
+  /**
+   * Same as [runFromChildZone] but catches uncaught errors and gives them to
+   * [handleUncaughtError].
+   */
+  runFromChildZoneGuarded(f());
+
+  /**
+   * Runs [f] asynchronously in [zone].
+   */
+  void runAsync(void f(), _Zone zone);
 
   /**
    * Creates a Timer where the callback is executed in this zone.
    */
   Timer createTimer(Duration duration, void callback());
 
   /**
    * Creates a periodic Timer where the callback is executed in this zone.
    */
   Timer createPeriodicTimer(Duration duration, void callback(Timer timer));
@@ skipping 82 matching lines @@
    *
    * This method is called when an operation has decremented the
    * outstanding-callback count, or when a child has been removed.
    */
   void _checkIfDone() {
     if (!_isExecutingCallback && _openCallbacks == 0 && _children.isEmpty) {
       _dispose();
     }
   }
 
-  /**
-   * Executes the given callback in this zone.
-   *
-   * Decrements the open-callback counter and checks (after the call) if the
-   * zone is done.
-   */
-  void executeCallback(void fun()) {
+  void executeCallback(void f()) {
     _openCallbacks--;
-    this._runUnguarded(fun);
+    this._runUnguarded(f);
   }
 
-  /**
-   * Same as [executeCallback] but catches uncaught errors and gives them to
-   * [handleUncaughtError].
-   */
-  void executeCallbackGuarded(void fun()) {
+  void executeCallbackGuarded(void f()) {
     _openCallbacks--;
-    this._runGuarded(fun);
+    this._runGuarded(f);
   }
 
-  /**
-   * Same as [executeCallback] but doesn't decrement the open-callback counter.
-   */
-  void executePeriodicCallback(void fun()) {
-    this._runUnguarded(fun);
+  void executePeriodicCallback(void f()) {
+    this._runUnguarded(f);
   }
 
-  /**
-   * Same as [executePeriodicCallback] but catches uncaught errors and gives
-   * them to [handleUncaughtError].
-   */
-  void executePeriodicCallbackGuarded(void fun()) {
-    this._runGuarded(fun);
+  void executePeriodicCallbackGuarded(void f()) {
+    this._runGuarded(f);
   }
 
-  _runInZone(fun(), bool handleUncaught) {
+  runFromChildZone(f()) => this._runUnguarded(f);
+  runFromChildZoneGuarded(f()) => this._runGuarded(f);
+
+  _runInZone(f(), bool handleUncaught) {
     if (identical(_Zone._current, this)
         && !handleUncaught
         && _isExecutingCallback) {
       // No need to go through a try/catch.
-      return fun();
+      return f();
     }
 
     _Zone oldZone = _Zone._current;
     _Zone._current = this;
     // While we are executing the function we don't want to have other
     // synchronous calls to think that they closed the zone. By incrementing
     // the _openCallbacks count we make sure that their test will fail.
     // As a side effect it will make nested calls faster since they are
     // (probably) in the same zone and have an _openCallbacks > 0.
     bool oldIsExecuting = _isExecutingCallback;
     _isExecutingCallback = true;
     // TODO(430): remove second try when VM bug is fixed.
     try {
       try {
-        return fun();
+        return f();
       } catch(e, s) {
         if (handleUncaught) {
           handleUncaughtError(_asyncError(e, s));
         } else {
           rethrow;
         }
       }
     } finally {
       _isExecutingCallback = oldIsExecuting;
       _Zone._current = oldZone;
       _checkIfDone();
     }
   }
 
   /**
    * Runs the function and catches uncaught errors.
    *
    * Uncaught errors are given to [handleUncaughtError].
    */
-  _runGuarded(void fun()) {
-    return _runInZone(fun, true);
+  _runGuarded(void f()) {
+    return _runInZone(f, true);
   }
 
   /**
    * Runs the function but doesn't catch uncaught errors.
    */
-  _runUnguarded(void fun()) {
-    return _runInZone(fun, false);
+  _runUnguarded(void f()) {
+    return _runInZone(f, false);
   }
 
-  runAsync(void fun()) {
-    _openCallbacks++;
-    _scheduleAsyncCallback(() {
-      _openCallbacks--;
-      _runGuarded(fun);
-    });
-  }
+  runAsync(void f(), _Zone zone) => _parentZone.runAsync(f, zone);
 
+  // TODO(floitsch): the zone should just forward to the parent zone. The
+  // default zone should then create the _ZoneTimer.
   Timer createTimer(Duration duration, void callback()) {
     return new _ZoneTimer(this, duration, callback);
   }
 
+  // TODO(floitsch): the zone should just forward to the parent zone. The
+  // default zone should then create the _ZoneTimer.
   Timer createPeriodicTimer(Duration duration, void callback(Timer timer)) {
     return new _PeriodicZoneTimer(this, duration, callback);
   }
 
   void _addChild(_Zone child) {
+    // TODO(floitsch): the zone should just increment a counter, but not keep
+    // a reference to the child.
     _children.add(child);
   }
 
   void _removeChild(_Zone child) {
     assert(!_children.isEmpty);
     // Children are usually added and removed fifo or filo.
     if (identical(_children.last, child)) {
       _children.length--;
       _checkIfDone();
       return;
@@ skipping 24 matching lines @@
     _scheduleAsyncCallback(() {
       print("Uncaught Error: ${error}");
       var trace = getAttachedStackTrace(error);
       _attachStackTrace(error, null);
       if (trace != null) {
         print("Stack Trace:\n$trace\n");
       }
       throw error;
     });
   }
+
+  void runAsync(void f(), _Zone zone) {
+    if (identical(this, zone)) {
+      // No need to go through the zone when it's the default zone anyways.
+      _scheduleAsyncCallback(f);
+      return;
+    }
+    zone.expectCallback();
+    _scheduleAsyncCallback(() {
+      zone.executeCallbackGuarded(f);
+    });
+  }
 }
 
 typedef void _CompletionCallback();
 
 /**
  * A zone that executes a callback when the zone is dead.
  */
 class _WaitForCompletionZone extends _ZoneBase {
   final _CompletionCallback _onDone;
 
   _WaitForCompletionZone(_Zone parentZone, this._onDone) : super(parentZone);
 
   /**
    * Runs the given function asynchronously. Executes the [_onDone] callback
    * when the zone is done.
    */
-  runWaitForCompletion(void fun()) {
-    return this._runUnguarded(fun);
+  runWaitForCompletion(void f()) {
+    return this._runUnguarded(f);
   }
 
   _dispose() {
     super._dispose();
     _onDone();
   }
 
   String toString() => "WaitForCompletion ${super.toString()}";
 }
 
 typedef void _HandleErrorCallback(error);
 
 /**
  * A zone that collects all uncaught errors and provides them in a stream.
  * The stream is closed when the zone is done.
  */
 class _CatchErrorsZone extends _WaitForCompletionZone {
   final _HandleErrorCallback _handleError;
 
   _CatchErrorsZone(_Zone parentZone, this._handleError, void onDone())
-    : super(parentZone, onDone);
+      : super(parentZone, onDone);
 
   _Zone get _errorZone => this;
 
   handleUncaughtError(error) {
     try {
       _handleError(error);
     } catch(e, s) {
       if (identical(e, s)) {
         _parentZone.handleUncaughtError(error);
       } else {
         _parentZone.handleUncaughtError(_asyncError(e, s));
       }
     }
   }
 
   /**
    * Runs the given function asynchronously. Executes the [_onDone] callback
    * when the zone is done.
    */
-  runWaitForCompletion(void fun()) {
-    return this._runGuarded(fun);
+  runWaitForCompletion(void f()) {
+    return this._runGuarded(f);
   }
 
-  String toString() => "WithErrors ${super.toString()}";
+  String toString() => "CatchErrors ${super.toString()}";
+}
+
+typedef void _RunAsyncInterceptor(void callback());
+
+class _RunAsyncZone extends _ZoneBase {
+  final _RunAsyncInterceptor _runAsyncInterceptor;
+
+  _RunAsyncZone(_Zone parentZone, this._runAsyncInterceptor)
+      : super(parentZone);
+
+  void runAsync(void callback(), _Zone zone) {
+    zone.expectCallback();
+    _parentZone.runFromChildZone(() {
+      _runAsyncInterceptor(() => zone.executeCallbackGuarded(callback));
+    });
+  }
 }
 
 typedef void _TimerCallback();
 
 /**
  * A [Timer] class that takes zones into account.
  */
 class _ZoneTimer implements Timer {
   final _Zone _zone;
   final _TimerCallback _callback;
@@ skipping 45 matching lines @@
   }
 }
 
 /**
  * Runs [body] in its own zone.
  *
  * If [onError] is non-null the zone is considered an error zone. All uncaught
  * errors, synchronous or asynchronous, in the zone are caught and handled
  * by the callback.
  *
- * [onDone] (if non-null) is invoked when the zone has no more outstanding
- * callbacks.
+ * The [onDone] handler (if non-null) is invoked when the zone has no more
+ * outstanding callbacks.
+ *
+ * The [onRunAsync] handler (if non-null) is invoked when the [body] executes
+ * [runAsync].  The handler is invoked in the outer zone and can therefore
+ * execute [runAsync] without recursing. The given callback must be
+ * executed eventually. Otherwise the nested zone will not complete. It must be
+ * executed only once.
  *
  * Examples:
  *
  *     runZonedExperimental(() {
  *       new Future(() { throw "asynchronous error"; });
  *     }, onError: print);  // Will print "asynchronous error".
  *
  * The following example prints "1", "2", "3", "4" in this order.
  *
  *     runZonedExperimental(() {
  *       print(1);
  *       new Future.value(3).then(print);
  *     }, onDone: () { print(4); });
  *     print(2);
  *
  * Errors may never cross error-zone boundaries. This is intuitive for leaving
  * a zone, but it also applies for errors that would enter an error-zone.
  * Errors that try to cross error-zone boundaries are considered uncaught.
  *
  *     var future = new Future.value(499);
  *     runZonedExperimental(() {
  *       future = future.then((_) { throw "error in first error-zone"; });
  *       runZonedExperimental(() {
  *         future = future.catchError((e) { print("Never reached!"); });
  *       }, onError: (e) { print("unused error handler"); });
  *     }, onError: (e) { print("catches error of first error-zone."); });
  *
+ * The following example prints the stack trace whenever a callback is
+ * registered using [runAsync] (which is also used by [Completer]s and
+ * [StreamController]s.
+ *
+ *     printStackTrace() { try { throw 0; } catch(e, s) { print(s); } }
+ *     runZonedExperimental(body, onRunAsync: (callback) {
+ *       printStackTrace();
+ *       runAsync(callback);
+ *     });
  */
-runZonedExperimental(body(), { void onError(error), void onDone() }) {
+runZonedExperimental(body(),
+                     { void onRunAsync(void callback()),
+                       void onError(error),
+                       void onDone() }) {
+  if (onRunAsync != null) {
+    _RunAsyncZone zone = new _RunAsyncZone(_Zone._current, onRunAsync);
+    return zone._runUnguarded(() {
+      return runZonedExperimental(body, onError: onError, onDone: onDone);
+    });
+  }
+
   // TODO(floitsch): we probably still want to install a new Zone.
   if (onError == null && onDone == null) return body();
   if (onError == null) {
     _WaitForCompletionZone zone =
         new _WaitForCompletionZone(_Zone._current, onDone);
     return zone.runWaitForCompletion(body);
   }
   if (onDone == null) onDone = _nullDoneHandler;
   _CatchErrorsZone zone = new _CatchErrorsZone(_Zone._current, onError, onDone);
   return zone.runWaitForCompletion(body);
 }