async, await and asynchronous errors

A checkout page needs a price and a stock count, and each comes from a call that takes 300 ms. Awaited one after the other they cost at least 600 ms; started together, about 300. Either call can also fail, and an error that escapes the wrong line ends the program.

This lesson writes async functions with await, catches asynchronous errors with an ordinary try, and waits for several calls at once, with programs that ran on Dart 3.13.5.

An async function runs to its first await, then returns a future

Mark a function async and it may use await. Its body starts at once, inside the call, like any other function. At its first await it stops and hands its caller a future, and it finishes later, when the awaited future completes:

// An async function runs synchronously up to its first await, hands its caller a future, and finishes later.
Future<int> fetchPrice(String sku) async {
  print('fetchPrice: starts and runs to its first await');
  await Future.pause(const Duration(milliseconds: 20));
  print('fetchPrice: resumes after the await');
  return 499;
}

Future<void> main() async {
  print('main: calls fetchPrice');
  final pending = fetchPrice('pen');
  print('main: has ${pending.runtimeType}, is Future<int>: ${pending is Future<int>}');
  final price = await pending;
  print('main: price $price');
}

main: calls fetchPrice
fetchPrice: starts and runs to its first await
main: has Future<int>, is Future<int>: true
fetchPrice: resumes after the await
main: price 499

fetchPrice printed its first line before main got anything back. Then main held a Future<int> that had not completed, and the rest of fetchPrice ran 20 ms later. An await never blocks the thread: it hands control back to the event loop and resumes the function when the future completes. Step through the messages:

An async functionasync function: A function marked async. It may use await, always returns a future, runs synchronously up to its first await and finishes later, when the futures it awaits have completed. always returns a future. return 499 in a function declared Future<int> completes that future with 499, which is what the caller’s await produces.

try and catch work across await

Asynchronous errors arrive after the call that caused them, but await brings them back to one line: when the awaited future fails, the await throws its error right there. So the try, on, catch and finally of exceptions and errors work unchanged:

// An awaited future's error is thrown at the await, so an ordinary try, on, catch and finally handle it.
import 'dart:async';

Future<int> fetchStock(String sku) async {
  await Future.pause(const Duration(milliseconds: 10));
  if (sku == 'ink') throw TimeoutException('stock service did not answer for "$sku"');
  return 12;
}

Future<void> showStock(String sku) async {
  print('$sku: asking');
  try {
    final count = await fetchStock(sku);
    print('$sku: $count in stock');
  } on TimeoutException catch (e) {
    print('$sku: stock unknown (${e.message})');
  } finally {
    print('$sku: spinner stopped');
  }
}

Future<void> main() async {
  await showStock('pen');
  await showStock('ink');
}

pen: asking
pen: 12 in stock
pen: spinner stopped
ink: asking
ink: stock unknown (stock service did not answer for "ink")
ink: spinner stopped

For pen the stock arrived. For ink, fetchStock failed 10 ms after it was called, the await in showStock threw the TimeoutException, and on TimeoutException handled it; finally stopped the spinner on both paths. That is the main gain over then and catchError: asynchronous errors are handled with the same statements, in the same order, as synchronous ones.

The same holds one level up. main awaited showStock twice, so if showStock itself had thrown, the error would have reached main at that await, and with no try there the program would end with exit code 255.

Start the calls first, then await them together

Two awaits in a row wait one after the other: the second call does not start until the first has finished. When the calls are independent, start both and wait for both. Put the futures in a record and call .wait on it; the result is a record of values that a pattern unpacks:

// Two calls of 300 ms each: awaited one after the other, then started together and awaited as a record.
Future<int> fetchPrice(List<String> log) async {
  log.add('price starts');
  await Future.pause(const Duration(milliseconds: 300));
  log.add('price ends');
  return 499;
}

Future<int> fetchStock(List<String> log) async {
  log.add('stock starts');
  await Future.pause(const Duration(milliseconds: 300));
  log.add('stock ends');
  return 12;
}

Future<void> main() async {
  final clock = Stopwatch()..start();
  final one = <String>[];
  final price1 = await fetchPrice(one);
  final stock1 = await fetchStock(one);
  final sequential = clock.elapsedMilliseconds;
  print('one after the other: ${one.join(', ')}');
  print('  price $price1, stock $stock1, at least 600 ms: ${sequential >= 600}');

  clock.reset();
  final both = <String>[];
  final (price2, stock2) = await (fetchPrice(both), fetchStock(both)).wait;
  final parallel = clock.elapsedMilliseconds;
  print('started together: ${both.join(', ')}');
  print('  price $price2, stock $stock2, under 600 ms: ${parallel < 600}');
}

one after the other: price starts, price ends, stock starts, stock ends
  price 499, stock 12, at least 600 ms: true
started together: price starts, stock starts, price ends, stock ends
  price 499, stock 12, under 600 ms: true

The log shows the difference. In turn, the stock call started only after the price call had ended, so the pair took at least 600 ms. Together, both calls were running before either ended, and the pair took under 600 ms, close to the 300 ms of one call. Future.wait does the same for a list of futures of one type.

Three more tools finish the job. A ParallelWaitError reports which calls failed and keeps the values of the rest. timeout gives up waiting after a deadline you choose, and a retry tries again after growing pauses. Lint rules, the unawaited function and a zonezone: A dart:async context in which code and the callbacks it schedules run. A zone can bring its own handler for asynchronous errors that nothing else handles.’s error handler deal with the futures that nobody awaits.

Partial failures, timeouts and retries, with recorded runs Pro: opens with a Pro, Premium or Ultimate pass

Lost futures, the lint rules that find them and a zone for stray errors Pro: opens with a Pro, Premium or Ultimate pass

Practise

Check the three ideas of the sections above, async functions, a try around an await and parallel waits, in a short session that explains every answer:

Interview questions

Warm-up (fresher): What does an async function return, and when does its body start running?

It returns a future, always: Future<T> for a function that returns a T, and Future<void> when it returns nothing. Its body starts at once, during the call, and runs synchronously up to its first await. There it stops, and the caller receives the future, which has not completed yet. The rest of the body runs later, when the awaited future completes, and the function’s return value then completes the caller’s future. In async_flow.dart, fetchPrice printed its first line before main received the Future<int>.

Three longer questions take these ideas into failures and deadlines:

Key takeaways

• An async function runs at once up to its first await, returns a future to its caller and finishes when the awaited future completes.
• An await throws the error of a future that failed, so try, on, catch and finally handle asynchronous errors like synchronous ones.
• Two awaits in a row run the calls one after the other; starting both and awaiting a record’s .wait runs them together, in about the time of the slower one.