The Event Loop and Dart

Dart’s event loop and queues

Tip: Chain futures to specify task order

// BAD because of no explicit dependency between setting and using// the variable.
future.then(...set an important variable...);Timer.run(() {...use the important variable...});

// BETTER because the dependency is explicit.
future.then(...set an important variable...)
  .then((_) {...use the important variable...});

// MAYBE EVEN BETTER: Explicit dependency plus delayed execution.
future.then(...set an important variable...)
  .then((_) {new Future(() {...use the important variable...})});

How to schedule a task

1. The Future class, which adds an item to the end of the event queue.

2. The top-level scheduleMicrotask() function, which adds an item to the end of the microtask queue.

Use the appropriate queue (usually: the event queue)

Event queue: new Future()

// Adds a task to the event queue.new Future(() {
  // ...code goes here...});

new Future(() => 21)
    .then((v) => v*2)
    .then((v) => print(v));

// After a one-second delay, adds a task to the event queue.new Future.delayed(const Duration(seconds:1), () {
  // ...code goes here...});

1. The function that you pass into Future’s then() method executes immediately when the Future completes. (The function isn’t enqueued, it’s just called.)

2. If a Future is already complete before then() is invoked on it, then a task is added to the microtask queue, and that task executes the function passed into then().

3. The Future() and Future.delayed() constructors don’t complete immediately; they add an item to the event queue.

4. The Future.value() constructor completes in a microtask, similar to #2.

5. 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: scheduleMicrotask()

scheduleMicrotask(() {
  // ...code goes here...});

Use isolates or workers if necessary

Test your understanding

Question #1

import 'dart:async';

void main() {
  print('main #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'));

  scheduleMicrotask(() => print('microtask #2 of 2'));

  print('main #2 of 2');
}

main #1 of 2
main #2 of 2
microtask #1 of 2
microtask #2 of 2
future #2 of 3
future #3 of 3
future #1 (delayed)

1. code in the main() function

2. tasks in the microtask queue (scheduleMicrotask())

3. tasks in the event queue (new Future() or new Future.delayed())

Question #2

import 'dart:async';

void main() {
  print('main #1 of 2');
  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');
        scheduleMicrotask(() => print('microtask #0 (from future #2b)'));
      })
      .then((_) => print('future #2c'));

  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'));
  scheduleMicrotask(() => print('microtask #3 of 3'));
  print('main #2 of 2');
}

main #1 of 2
main #2 of 2
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
microtask #0 (from future #2b)
future #3a (a new future)
future #3b
future #1 (delayed)

• 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 for more information.

Annotated sample and output

Summary

• A Dart app’s event loop executes tasks from two queues: the event queue and the microtask queue.

• The event queue has entries from both Dart (futures, timers, isolate messages, and so on) and the system (user actions, I/O, and so on).

• Currently, the microtask queue has entries only from Dart, but we expect it to be merged with the browser microtask queue.

• The event loop empties the microtask queue before dequeuing and handling the next item on the event queue.

• Once both queues are empty, the app has completed its work and (depending on its embedder) can exit.

• The main() function and all items from the microtask and event queues run on the Dart app’s main isolate.

• If possible, put it on the event queue (using new Future() or new Future.delayed()).

• Use Future’s then() or whenComplete() method to specify task order.

• To avoid starving the event loop, keep the microtask queue as short as possible.

• To keep your app responsive, avoid compute-intensive tasks on either event loop.

• To perform compute-intensive tasks, create additional isolates or workers.

• Futures tutorial

• dart:async library tour

• dart:async API reference