runAsync name change

src/site/articles/event-loop/index.markdown

 ---
 layout: default
 title: "The Event Loop and Dart"
 description: "Learn how Dart handles the event queue and microtask queue, so you can write better asynchronous code with fewer surprises."
 rel:
     author: kathy-walrath
 has-permalinks: true
 article:
   written_on: 2013-09-30
+  updated_on: 2013-10-22
   collection: performance
 ---
 
 # {{ page.title }}
 
 _Written by Kathy Walrath
 <br>
-September 2013_
+September 2013 (updated October 2013)_
 
 Asynchronous code is everywhere in Dart.
 Many library functions return Future objects,
 and you can register handlers to respond to events such as
 mouse clicks, file I/O completions, and timer expirations.
 
 This article describes Dart’s event loop architecture,
 so that you can write better asynchronous code with fewer surprises.
 You’ll learn options for scheduling future tasks,
 and you’ll be able to predict the order of execution.
@@ skipping 110 matching lines @@
 Once both queues are empty and no more events are expected,
 the app’s _embedder_ (such as the browser or a test framework)
 can dispose of the app.
 
 <aside class="alert alert-info" markdown="1">
 **Note:**
 If a web app’s user closes its window,
 then the web app might exit before its event queue is empty.
 </aside>
 
-![flowchart: main() -> microtasks -> next event -> microtasks -> ....](images/both-queues.png)
+![flowchart: main() -> microtasks -> next event -> microtasks -> ...](images/both-queues.png)
 
 <aside class="alert alert-warning" markdown="1">
 **Important:**
 While the event loop is executing tasks from the microtask queue,
 the event queue is stuck:
 the app can’t
 draw graphics, handle mouse clicks, react to I/O, and so on.
 </aside>
 
 Although you can predict the _order_ of task execution,
@@ skipping 47 matching lines @@
 process other events from the event queue.
 The next section gives details on scheduling code to run later.
 
 ## How to schedule a task
 
 When you need to specify some code to be executed later,
 you can use the following APIs provided by the dart:async library:
 
 1. The **Future** class,
 which adds an item to the end of the **event queue**.
-1. The top-level **runAsync()** function,
+1. The top-level **scheduleMicrotask()** function,
 which adds an item to the end of the **microtask queue**.
 
+<aside class="alert alert-info" markdown="1">
+**Note:**
+The **scheduleMicrotask()** function used to be named **runAsync()**.
+(See the [announcement](https://groups.google.com/a/dartlang.org/forum/#!msg/misc/7sAIhWXfIKQ/PzYJy1QqtWUJ).)
+</aside>
+
 Examples of using these APIs are in the next section under
 [Event queue: new Future()](#event-queue-new-future) and
-[Microtask queue: runAsync()](#microtask-queue-runasync).
+[Microtask queue: scheduleMicrotask()](#microtask-queue).
 
 ### Use the appropriate queue (usually: the event queue)
 
 Whenever possible, schedule tasks on the event queue, with Future.
 Using the event queue helps keep the the microtask queue short,
 reducing the likelihood of the microtask queue starving the event queue.
 
 If a task absolutely must complete before
 any items from the event queue are handled,
 then you should usually just execute the function immediately.
-If you can’t, then use runAsync() to add an item to the microtask queue.
+If you can’t, then use scheduleMicrotask() to
+add an item to the microtask queue.
 For example, in a web app use a microtask to
 avoid prematurely releasing a js-interop proxy or
 ending an IndexedDB transaction or event handler.
 
-![shows chain of event handler execution, with tasks added using Future and runAsync().](images/scheduling-tasks.png)
+![shows chain of event handler execution, with tasks added using Future and scheduleMicrotask().](images/scheduling-tasks.png)
 
 
 #### Event queue: new Future()
 
 To schedule a task on the event queue,
 use `new Future()` or `new Future.delayed()`.
 These are two of the
 [Future](http://api.dartlang.org/dart_async/Future.html)
 constructors defined in the dart:async library.
 
@@ skipping 67 matching lines @@
 and _that_ task executes the function passed into then().
 1. The **Future()** and **Future.delayed()** constructors
 don’t complete immediately;
 they add an item to the event queue.
 1. The **Future.value()** constructor completes in a microtask,
 similar to #2.
 1. The **Future.sync()** constructor executes its function argument immediately
 and (unless that function returns a Future)
 completes in a microtask, similar to #2.
 
-#### Microtask queue: runAsync()
+#### Microtask queue: scheduleMicrotask()
 
-The dart:async library defines runAsync() as a top-level function.
-You can call runAsync() like this:
+The dart:async library defines scheduleMicrotask() as a top-level function.
+You can call scheduleMicrotask() like this:
 
 {% prettify dart %}
-runAsync(() {
+scheduleMicrotask(() {
   // ...code goes here...
 });
 {% endprettify %}
 
 Due to bugs [9001](https://code.google.com/p/dart/issues/detail?id=9001)
 and [9002](https://code.google.com/p/dart/issues/detail?id=9002),
-the first call to runAsync() schedules a task on the event queue;
+the first call to scheduleMicrotask() schedules a task on the event queue;
 this task creates the microtask queue and
-enqueues the function specified to runAsync().
+enqueues the function specified to scheduleMicrotask().
 As long as the microtask queue has at least one entry,
-subsequent calls to runAsync() correctly add to the microtask queue.
+subsequent calls to scheduleMicrotask() correctly add to the microtask queue.
 Once the microtask queue is empty,
-it must be created again the next time runAsync() is called.
+it must be created again the next time scheduleMicrotask() is called.
 
 The upshot of these bugs:
-The first task that you schedule with runAsync() seems
+The first task that you schedule with scheduleMicrotask() seems
 like it’s on the event queue.
 
-A workaround is to put your first call to runAsync() before
+A workaround is to put your first call to scheduleMicrotask() before
 your first call to new Future().
 This creates the microtask queue before
 executing other tasks on the event queue.
 However, it doesn’t stop external events from being added to the event queue.
 It also doesn’t help when you have a delayed task.
 
 Another way to add a task to the microtask queue is
 to invoke then() on a Future that’s already complete.
 See the previous section for more information.
 
@@ skipping 37 matching lines @@
 Still, won’t you feel smart if you can answer these questions correctly?
 
 ### Question #1
 
 What does this sample print out?
 
 {% prettify dart %}
 import 'dart:async';
 main() {
   print('main #1 of 2');
-  runAsync(() => print('runAsync #1 of 2'));
+  scheduleMicrotask(() => print('microtask #1 of 2'));
   
   new Future.delayed(new Duration(seconds:1),
                      () => print('future #1 (delayed)'));
   new Future(() => print('future #2 of 3'));
   new Future(() => print('future #3 of 3'));
     
-  runAsync(() => print('runAsync #2 of 2'));
+  scheduleMicrotask(() => print('microtask #2 of 2'));
 
   print('main #2 of 2');
 }
 {% endprettify %}
 
 The answer:
 
 <pre>
 main #1 of 2
 main #2 of 2
-runAsync #1 of 2
-runAsync #2 of 2
+microtask #1 of 2
+microtask #2 of 2
 future #2 of 3
 future #3 of 3
 future #1 (delayed)
 </pre>
 
 That order should be what you expected,
 since the example’s code executes in three batches:
 
 1. code in the main() function
-1. tasks in the microtask queue (runAsync())
+1. tasks in the microtask queue (scheduleMicrotask())
 1. tasks in the event queue (new Future() or new Future.delayed())
 
 Keep in mind that all the calls in the main() function execute synchronously,
 start to finish.
-First main() calls print(), then runAsync(),
+First main() calls print(), then scheduleMicrotask(),
 then new Future.delayed(), then new Future(), and so on.
 Only the callbacks—the code in the closure bodies specified as
-arguments to runAsync(), new Future.delayed(), and
+arguments to scheduleMicrotask(), new Future.delayed(), and
 new Future()—execute at a later time.
 
 <aside class="alert alert-info" markdown="1">
 **Note:**
-Currently, if you comment out the first call to runAsync,
-then the callbacks for futures #2 and #3 execute before runAsync #2.
+Currently, if you comment out the first call to scheduleMicrotask(),
+then the callbacks for futures #2 and #3 execute before microtask #2.
 This is due to bugs 9001 and 9002, as discussed in
-[Microtask queue: runAsync()](#microtask-queue-runasync).
+[Microtask queue: scheduleMicrotask()](#microtask-queue).
 </aside>
 
 ### Question #2
 
 Here’s a more complex example.
 If you can correctly predict the output of this code,
 you get a gold star.
 
 {% prettify dart %}
 import 'dart:async';
 main() {
   print('main #1 of 2');
-  runAsync(() => print('runAsync #1 of 3'));
+  scheduleMicrotask(() => print('microtask #1 of 3'));
 
   new Future.delayed(new Duration(seconds:1),
       () => print('future #1 (delayed)'));
   
   new Future(() => print('future #2 of 4'))
       .then((_) => print('future #2a'))
       .then((_) {
         print('future #2b');
-        runAsync(() => print('runAsync #0 (from future #2b)'));
+        scheduleMicrotask(() => print('microtask #0 (from future #2b)'));
       })
       .then((_) => print('future #2c'));
 
-  runAsync(() => print('runAsync #2 of 3'));
+  scheduleMicrotask(() => print('microtask #2 of 3'));
 
   new Future(() => print('future #3 of 4'))
       .then((_) => new Future(
                    () => print('future #3a (a new future)')))
       .then((_) => print('future #3b'));
 
   new Future(() => print('future #4 of 4'));
-  runAsync(() => print('runAsync #3 of 3'));
+  scheduleMicrotask(() => print('microtask #3 of 3'));
   print('main #2 of 2');
 }
 {% endprettify %}
 
 The output, assuming bugs 9001/9002 aren't fixed:
 
 <pre>
 main #1 of 2
 main #2 of 2
-runAsync #1 of 3
-runAsync #2 of 3
-runAsync #3 of 3
+microtask #1 of 3
+microtask #2 of 3
+microtask #3 of 3
 future #2 of 4
 future #2a
 future #2b
 future #2c
 future #3 of 4
 future #4 of 4
-runAsync #0 (from future #2b)
+microtask #0 (from future #2b)
 future #3a (a new future)
 future #3b
 future #1 (delayed)
 </pre>
 
 <aside class="alert alert-info" markdown="1">
 **Note:**
 Due to bugs 9001/9002,
-runAsync #0 executes after future #4;
+microtask #0 executes after future #4;
 it should instead execute before future #3.
 This bug shows up because by the time future #2b executes,
-no runAsync tasks are queued,
-so runAsync #0 results in a new task on the event queue,
+no microtasks are queued,
+so microtask #0 results in a new task on the event queue,
 which creates a new microtask queue.
-This microtask queue has a task for runAsync #0.
-If you comment out runAsync #1,
-then the runAsync tasks all appear together just after future #2c,
+This microtask queue contains microtask #0.
+If you comment out microtask #1,
+then the microtasks all appear together just after future #2c,
 and before future #3.
 </aside>
 
 Like before, the main() function executes,
-and then the tasks on the microtask queue,
-and then those on the event queue.
+and then everything on the microtask queue,
+and then tasks on the event queue.
 Here are a few interesting points:
 
 * When the then() callback for future 3 calls new Future(),
 it creates a new task (#3a) that’s added to the end of the event queue.
 * All the then() callbacks execute as soon as
 the Future they’re invoked on completes.
 Thus, future 2, 2a, 2b, and 2c execute all in one go,
 before control returns to the embedder.
 Similarly, future 3a and 3b execute all in one go.
 * If you change the 3a code from
 `then((_) => new Future(...))` to
 `then((_) {new Future(...); })`,
 then "future #3b" appears earlier
 (after future #3, instead of future #3a).
 The reason is that returning a Future from your callback
 is how you get then() (which itself returns a new Future)
 to _chain_ those two Futures together,
 so that the Future returned by then() completes
 when the Future returned by the callback completes.
 See the [then() reference](http://api.dartlang.org/docs/releases/latest/dart_async/Future.html#then)
 for more information.
 
 
 #### Annotated sample and output
 
 Here are some figures that might clarify the answer to question #2.
 First, here’s the annotated program source:
 
-![runAsync lines (which add a microtask) are gold; new Future lines (which schedule an event) are blue](images/test-annotated.png)
+![Lines that schedule a microtask are gold; lines that schedule an event are blue](images/test-annotated.png)
 
 And here’s what the queues and output look like at various points in time,
 assuming no external events come in:
 
 ![3 columns: Time, Output, Queues](images/test-queue-output.png)
 
 
 ## Summary
 
 You should now understand Dart’s event loops and how to schedule tasks.
@@ skipping 24 matching lines @@
 avoid compute-intensive tasks on either event loop.
 * To perform compute-intensive tasks,
 create additional isolates or workers.
 
 As you write asynchronous code, you might find these resources helpful:
 
 * [Using Future Based APIs](/articles/using-future-based-apis/)
 * [Futures and Error Handling](/articles/futures-and-error-handling/)
 * [dart:async - Asynchronous Programming](/docs/dart-up-and-running/contents/ch03.html#ch03-asynchronous-programming) section of the library tour
 * [dart:async API reference](http://api.dartlang.org/dart_async.html)