Asynchronous programming: futures, async, await

This codelab teaches you how to write asynchronous code usingfutures and the async and await keywords. Using embedded DartPadeditors, you can test your knowledge by running example code and completingexercises.

To get the most out of this codelab, you should have the following:

• Knowledge of basic Dart syntax.
• Some experience writing asynchronous code in another language.

This codelab covers the following material:

• How and when to use the async and await keywords.
• How using async and await affects execution order.
• How to handle errors from an asynchronous call using try-catch expressionsin async functions.

Estimated time to complete this codelab: 40-60 minutes.

Note: This page uses embedded DartPads to display examples and exercises. If you see empty boxes instead of DartPads, go to theDartPad troubleshooting page.

Why asynchronous code matters

Asynchronous operations let your program complete work while waiting foranother operation to finish. Here are some common asynchronous operations:

• Fetching data over a network.
• Writing to a database.
• Reading data from a file.

To perform asynchronous operations in Dart, you can use the Future classand the async and await keywords.

Example: Incorrectly using an asynchronous function

The following example shows the wrong way to use an asynchronous function(fetchUserOrder()). Later you’ll fix the example using async and await.Before running this example, try to spot the issue – what do you think theoutput will be?

void main() async { ··· }

Future<void> main() async { ··· }

print(await createOrderMessage());

String createOrderMessage() {  var order = fetchUserOrder();  return 'Your order is: $order';}Future<String> fetchUserOrder() =>    // Imagine that this function is    // more complex and slow.    Future.delayed(      Duration(seconds: 2),      () => 'Large Latte',    );void main() {  print('Fetching user order…');  print(createOrderMessage());}

Fetching user order…Your order is: Instance of _Future<String>

Future<String>  createOrderMessage() async {  var order = await fetchUserOrder();  return 'Your order is: $order';}Future<String>  fetchUserOrder() =>    // Imagine that this function is    // more complex and slow.    Future.delayed(      Duration(seconds: 2),      () => 'Large Latte',    );Future<void>  main() async {  print('Fetching user order…');  print(await createOrderMessage());}

Fetching user order…Your order is: Large Latte

var order = await fetchUserOrder();print('Awaiting user order…');

If your code passes the tests, you can ignore info-level messages.

Handling errors

To handle errors in an async function, use try-catch:

try {
  var order = await fetchUserOrder();
  print('Awaiting user order...');
} catch (err) {
  print('Caught error: $err');
}

Within an async function, you can write try-catch clausesthe same way you would in synchronous code.

Example: async and await with try-catch

Run the following example to see how to handle an error from anasynchronous function. What do you think the output will be?

Exercise: Practice handling errors

The following exercise provides practice handling errors with asynchronous code,using the approach described in the previous section. To simulate asynchronousoperations, your code will call the following function, which is provided for you:

Use async and await to implement an asynchronous changeUsername() functionthat does the following:

• Calls the provided asynchronous function fetchNewUsername() and returns its result.
  • Example return value from changeUsername(): "jane_smith_92"
• Catches any error that occurs and returns the string value of the error.
  • You can use thetoString()method to stringify bothExceptions andErrors.

Exercise: Putting it all together

It’s time to practice what you’ve learned in one final exercise.To simulate asynchronous operations, this exercise provides the asynchronousfunctions fetchUsername() and logoutUser():

Write the following:

Part 1: addHello()

• Write a function addHello() that takes a single String argument.
• addHello() returns its String argument preceded by ‘Hello ‘.Example: addHello('Jon') returns 'Hello Jon'.

Part 2: greetUser()

• Write a function greetUser() that takes no arguments.
• To get the username, greetUser() calls the provided asynchronousfunction fetchUsername().
• greetUser() creates a greeting for the user by calling addHello(),passing it the username, and returning the result.Example: If fetchUsername() returns 'Jenny', thengreetUser() returns 'Hello Jenny'.

Part 3: sayGoodbye()

• Write a function sayGoodbye() that does the following:
  • Takes no arguments.
  • Catches any errors.
  • Calls the provided asynchronous function logoutUser().
• If logoutUser() fails, sayGoodbye() returns any string you like.
• If logoutUser() succeeds, sayGoodbye() returns the string'<result> Thanks, see you next time', where <result> isthe String value returned by calling logoutUser().

What’s next?

Congratulations, you’ve finished the codelab! If you’d like to learn more, hereare some suggestions for where to go next:

• Play with DartPad.
• Try another codelab.
• Learn more about futures and asynchrony:
  • Streams tutorial:Learn how to work with a sequence of asynchronous events.
  • Dart videos from Google:Watch one or more of the videos about asynchronous coding.Or, if you prefer, read the articles that are based on these videos.(Start with isolates and event loops.)
• Get the Dart SDK.

If you’re interested in using embedded DartPads, like this codelab does, seebest practices for using DartPad in tutorials.