Rename runAsync to scheduleMicrotask.

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;
 
 typedef dynamic ZoneCallback();
 typedef dynamic ZoneUnaryCallback(arg);
 typedef dynamic ZoneBinaryCallback(arg1, arg2);
 
 typedef dynamic HandleUncaughtErrorHandler(
     Zone self, ZoneDelegate parent, Zone zone, error, StackTrace stackTrace);
 typedef dynamic RunHandler(Zone self, ZoneDelegate parent, Zone zone, f());
 typedef dynamic RunUnaryHandler(
     Zone self, ZoneDelegate parent, Zone zone, f(arg), arg);
 typedef dynamic RunBinaryHandler(
     Zone self, ZoneDelegate parent, Zone zone, f(arg1, arg2), arg1, arg2);
 typedef ZoneCallback RegisterCallbackHandler(
     Zone self, ZoneDelegate parent, Zone zone, f());
 typedef ZoneUnaryCallback RegisterUnaryCallbackHandler(
     Zone self, ZoneDelegate parent, Zone zone, f(arg));
 typedef ZoneBinaryCallback RegisterBinaryCallbackHandler(
     Zone self, ZoneDelegate parent, Zone zone, f(arg1, arg2));
 typedef void ScheduleMicrotaskHandler(
     Zone self, ZoneDelegate parent, Zone zone, f());
+@deprecated
+typedef void RunAsyncHandler(
+    Zone self, ZoneDelegate parent, Zone zone, f());
 typedef Timer CreateTimerHandler(
     Zone self, ZoneDelegate parent, Zone zone, Duration duration, void f());
 typedef Timer CreatePeriodicTimerHandler(
     Zone self, ZoneDelegate parent, Zone zone,
     Duration period, void f(Timer timer));
 typedef Zone ForkHandler(Zone self, ZoneDelegate parent, Zone zone,
                          ZoneSpecification specification,
                          Map<Symbol, dynamic> zoneValues);
 
 /**
  * This class provides the specification for a forked zone.
  *
  * When forking a new zone (see [Zone.fork]) one can override the default
  * behavior of the zone by providing callbacks. These callbacks must be
  * given in an instance of this class.
  *
  * Handlers have the same signature as the same-named methods on [Zone] but
  * receive three additional arguments:
  *
  *   1. the zone the handlers are attached to (the "self" zone).
  *   2. a [ZoneDelegate] to the parent zone.
  *   3. the zone that first received the request (before the request was
  *     bubbled up).
  *
  * Handlers can either stop propagation the request (by simply not calling the
  * parent handler), or forward to the parent zone, potentially modifying the
  * arguments on the way.
+ *
+ * *The `runAsync` handler is deprecated. Use `scheduleMicrotask` instead.*
  */
 abstract class ZoneSpecification {
   /**
    * Creates a specification with the provided handlers.
    */
   const factory ZoneSpecification({
     dynamic handleUncaughtError(Zone self, ZoneDelegate parent, Zone zone,
                                 error, StackTrace stackTrace): null,
     dynamic run(Zone self, ZoneDelegate parent, Zone zone, f()): null,
     dynamic runUnary(
         Zone self, ZoneDelegate parent, Zone zone, f(arg), arg): null,
     dynamic runBinary(Zone self, ZoneDelegate parent, Zone zone,
                       f(arg1, arg2), arg1, arg2): null,
     ZoneCallback registerCallback(
         Zone self, ZoneDelegate parent, Zone zone, f()): null,
     ZoneUnaryCallback registerUnaryCallback(
         Zone self, ZoneDelegate parent, Zone zone, f(arg)): null,
     ZoneBinaryCallback registerBinaryCallback(
         Zone self, ZoneDelegate parent, Zone zone, f(arg1, arg2)): null,
     void scheduleMicrotask(
         Zone self, ZoneDelegate parent, Zone zone, f()): null,
+    void runAsync(
+        Zone self, ZoneDelegate parent, Zone zone, f()): null,
     Timer createTimer(Zone self, ZoneDelegate parent, Zone zone,
                       Duration duration, void f()): null,
     Timer createPeriodicTimer(Zone self, ZoneDelegate parent, Zone zone,
                               Duration period, void f(Timer timer)): null,
     Zone fork(Zone self, ZoneDelegate parent, Zone zone,
               ZoneSpecification specification, Map zoneValues): null
   }) = _ZoneSpecification;
 
   /**
    * Creates a specification from [other] with the provided handlers overriding
    * the ones in [other].
    */
   factory ZoneSpecification.from(ZoneSpecification other, {
     dynamic handleUncaughtError(Zone self, ZoneDelegate parent, Zone zone,
                                 error, StackTrace stackTrace): null,
     dynamic run(Zone self, ZoneDelegate parent, Zone zone, f()): null,
     dynamic runUnary(
         Zone self, ZoneDelegate parent, Zone zone, f(arg), arg): null,
     dynamic runBinary(Zone self, ZoneDelegate parent, Zone zone,
                       f(arg1, arg2), arg1, arg2): null,
     ZoneCallback registerCallback(
         Zone self, ZoneDelegate parent, Zone zone, f()): null,
     ZoneUnaryCallback registerUnaryCallback(
         Zone self, ZoneDelegate parent, Zone zone, f(arg)): null,
     ZoneBinaryCallback registerBinaryCallback(
         Zone self, ZoneDelegate parent, Zone zone, f(arg1, arg2)): null,
     void scheduleMicrotask(
         Zone self, ZoneDelegate parent, Zone zone, f()): null,
+    void runAsync(
+        Zone self, ZoneDelegate parent, Zone zone, f()): null,
     Timer createTimer(Zone self, ZoneDelegate parent, Zone zone,
                       Duration duration, void f()): null,
     Timer createPeriodicTimer(Zone self, ZoneDelegate parent, Zone zone,
                               Duration period, void f(Timer timer)): null,
     Zone fork(Zone self, ZoneDelegate parent, Zone zone,
               ZoneSpecification specification,
               Map<Symbol, dynamic> zoneValues): null
   }) {
     return new ZoneSpecification(
       handleUncaughtError: handleUncaughtError != null
                            ? handleUncaughtError
                            : other.handleUncaughtError,
       run: run != null ? run : other.run,
       runUnary: runUnary != null ? runUnary : other.runUnary,
       runBinary: runBinary != null ? runBinary : other.runBinary,
       registerCallback: registerCallback != null
                         ? registerCallback
                         : other.registerCallback,
       registerUnaryCallback: registerUnaryCallback != null
                          ? registerUnaryCallback
                          : other.registerUnaryCallback,
       registerBinaryCallback: registerBinaryCallback != null
                          ? registerBinaryCallback
                          : other.registerBinaryCallback,
       scheduleMicrotask: scheduleMicrotask != null
                          ? scheduleMicrotask
-                         : other.scheduleMicrotask,
+                         : (runAsync != null
+                            ? runAsync
+                            : other.scheduleMicrotask),
       createTimer : createTimer != null ? createTimer : other.createTimer,
       createPeriodicTimer: createPeriodicTimer != null
                            ? createPeriodicTimer
                            : other.createPeriodicTimer,
       fork: fork != null ? fork : other.fork);
   }
 
   HandleUncaughtErrorHandler get handleUncaughtError;
   RunHandler get run;
   RunUnaryHandler get runUnary;
   RunBinaryHandler get runBinary;
   RegisterCallbackHandler get registerCallback;
   RegisterUnaryCallbackHandler get registerUnaryCallback;
   RegisterBinaryCallbackHandler get registerBinaryCallback;
   ScheduleMicrotaskHandler get scheduleMicrotask;
+  @deprecated
+  RunAsyncHandler get runAsync;
   CreateTimerHandler get createTimer;
   CreatePeriodicTimerHandler get createPeriodicTimer;
   ForkHandler get fork;
 }
 
 /**
  * Internal [ZoneSpecification] class.
  *
  * The implementation wants to rely on the fact that the getters cannot change
  * dynamically. We thus require users to go through the redirecting
  * [ZoneSpecification] constructor which instantiates this class.
  */
 class _ZoneSpecification implements ZoneSpecification {
   const _ZoneSpecification({
     this.handleUncaughtError: null,
     this.run: null,
     this.runUnary: null,
     this.runBinary: null,
     this.registerCallback: null,
     this.registerUnaryCallback: null,
     this.registerBinaryCallback: null,
-    this.scheduleMicrotask: null,
+    scheduleMicrotask: null,
+    runAsync: null,
     this.createTimer: null,
     this.createPeriodicTimer: null,
     this.fork: null
-  });
+  }) : this.scheduleMicrotask =
+           scheduleMicrotask != null ? scheduleMicrotask : runAsync;
 
   // TODO(13406): Enable types when dart2js supports it.
   final /*HandleUncaughtErrorHandler*/ handleUncaughtError;
   final /*RunHandler*/ run;
   final /*RunUnaryHandler*/ runUnary;
   final /*RunBinaryHandler*/ runBinary;
   final /*RegisterCallbackHandler*/ registerCallback;
   final /*RegisterUnaryCallbackHandler*/ registerUnaryCallback;
   final /*RegisterBinaryCallbackHandler*/ registerBinaryCallback;
   final /*ScheduleMicrotaskHandler*/ scheduleMicrotask;
+  @deprecated
+  get runAsync => scheduleMicrotask;
   final /*CreateTimerHandler*/ createTimer;
   final /*CreatePeriodicTimerHandler*/ createPeriodicTimer;
   final /*ForkHandler*/ fork;
 }
 
 /**
  * This class wraps zones for delegation.
  *
  * When forwarding to parent zones one can't just invoke the parent zone's
  * exposed functions (like [Zone.run]), but one needs to provide more
  * information (like the zone the `run` was initiated). Zone callbacks thus
  * receive more information including this [ZoneDelegate] class. When delegating
  * to the parent zone one should go through the given instance instead of
  * directly invoking the parent zone.
  */
 abstract class ZoneDelegate {
   /// The [Zone] this class wraps.
   Zone get _zone;
 
   dynamic handleUncaughtError(Zone zone, error, StackTrace stackTrace);
   dynamic run(Zone zone, f());
   dynamic runUnary(Zone zone, f(arg), arg);
   dynamic runBinary(Zone zone, f(arg1, arg2), arg1, arg2);
   ZoneCallback registerCallback(Zone zone, f());
   ZoneUnaryCallback registerUnaryCallback(Zone zone, f(arg));
   ZoneBinaryCallback registerBinaryCallback(Zone zone, f(arg1, arg2));
+  @deprecated
+  void runAsync(Zone zone, f());
   void scheduleMicrotask(Zone zone, f());
   Timer createTimer(Zone zone, Duration duration, void f());
   Timer createPeriodicTimer(Zone zone, Duration period, void f(Timer timer));
   Zone fork(Zone zone, ZoneSpecification specification, Map zoneValues);
 }
 
 /**
  * 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 131 matching lines @@
    *      return (arg1, arg2) => thin.runBinary(registered, arg1, arg2);
    */
   ZoneBinaryCallback bindBinaryCallback(
       f(arg1, arg2), { bool runGuarded: true });
 
   /**
    * Runs [f] asynchronously.
    */
   void scheduleMicrotask(void f());
 
+  @deprecated
+  void runAsync(void f());
+
   /**
    * 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 period, void callback(Timer timer));
 
@@ skipping 84 matching lines @@
 
   void scheduleMicrotask(Zone zone, f()) {
     _CustomizedZone parent = _degelationTarget;
     while (parent._specification.scheduleMicrotask == null) {
       parent = parent.parent;
     }
     _ZoneDelegate grandParent = new _ZoneDelegate(parent.parent);
     (parent._specification.scheduleMicrotask)(parent, grandParent, zone, f);
   }
 
+  @deprecated
+  void runAsync(Zone zone, f()) {
+    scheduleMicrotask(zone, f());
+  }
+
   Timer createTimer(Zone zone, Duration duration, void f()) {
     _CustomizedZone parent = _degelationTarget;
     while (parent._specification.createTimer == null) {
       parent = parent.parent;
     }
     return (parent._specification.createTimer)(
         parent, new _ZoneDelegate(parent.parent), zone, duration, f);
   }
 
   Timer createPeriodicTimer(Zone zone, Duration period, void f(Timer timer)) {
@@ skipping 130 matching lines @@
   }
 
   ZoneBinaryCallback registerBinaryCallback(f(arg1, arg2)) {
     return new _ZoneDelegate(this).registerBinaryCallback(this, f);
   }
 
   void scheduleMicrotask(void f()) {
     new _ZoneDelegate(this).scheduleMicrotask(this, f);
   }
 
+  @deprecated
+  void runAsync(void f()) {
+    scheduleMicrotask(f);
+  }
+
   Timer createTimer(Duration duration, void f()) {
     return new _ZoneDelegate(this).createTimer(this, duration, f);
   }
 
   Timer createPeriodicTimer(Duration duration, void f(Timer timer)) {
     return new _ZoneDelegate(this).createPeriodicTimer(this, duration, f);
   }
 }
 
 void _rootHandleUncaughtError(
@@ skipping 177 matching lines @@
   if (onError != null) {
     return zone.runGuarded(body);
   } else {
     return zone.run(body);
   }
 }
 
 /**
  * Deprecated. Use `runZoned` instead or create your own [ZoneSpecification].
  *
- * 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.
+ * The [onScheduleMicrotask] handler (if non-null) is invoked when the [body]
+ * executes [scheduleMicrotask]. The handler is invoked in the outer zone and
+ * can therefore execute [scheduleMicrotask] without recursing. The given
+ * callback must be executed eventually. Otherwise the nested zone will not
+ * complete. It must be executed only once.
  *
  * The following example prints the stack trace whenever a callback is
- * registered using [runAsync] (which is also used by [Completer]s and
+ * registered using [scheduleMicrotask] (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);
+ *       scheduleMicrotask(callback);
  *     });
  *
  * Note: the `onDone` handler is ignored.
  */
 @deprecated
 runZonedExperimental(body(),
                      { void onRunAsync(void callback()),
                        void onError(error),
                        void onDone() }) {
   if (onRunAsync == null) {
@@ skipping 15 matching lines @@
     };
   }
   ScheduleMicrotaskHandler asyncHandler;
   if (onRunAsync != null) {
     asyncHandler = (Zone self, ZoneDelegate parent, Zone zone, f()) {
       self.parent.runUnary(onRunAsync, () => zone.runGuarded(f));
     };
   }
   ZoneSpecification specification =
     new ZoneSpecification(handleUncaughtError: errorHandler,
-                        scheduleMicrotask: asyncHandler);
+                          scheduleMicrotask: asyncHandler);
   Zone zone = Zone.current.fork(specification: specification);
   if (onError != null) {
     return zone.runGuarded(body);
   } else {
     return zone.run(body);
   }
 }