Exploring Dart's Async Library

(Warning: work in progress...)

Use Dart's async library to keep work off the main UI thread and help your users have a smooth and performant experience. The dart:async library contains classes for timers, futures, streams, and more. Effective use of dart:async keeps your apps easier to understand and your UI snappy.

Telling the future is easier when you have all the data.

The event loop


Or, why this all matters.

Dart programs, just like JavaScript, have no shared-state threads. The UI and the program use the same thread of execution, so when the UI is updating the program isn't running. Conversely, when the programming is running, the UI isn't updating. Keeping work off of the main thread means more time for the UI to respond to user input, which means the UI feels snappy and responsive.

The runtime maintains an event loop and a queue of work to perform. The event loops pops work items off of the queue, one after another. While one work item is handled, the other work items sit in the queue patiently.

Examples of work items can include callbacks for mouse move, mouse click, scroll events, database fetches, window resizes, and programatic callbacks. That is, all of the events and callbacks registered by your program or generated by the browser end up in the queue to be processed by the event loop. It's clear that keeping the individual work items small is key to a performant application and UI.

(Note, in Dart you can create new isolates if you want concurrent program execution. In JavaScript, you can create new Web Workers to achieve the same effect.)

Async programming


As an analogy, consider these two scenarios:

1) Send an email, stop doing any work at all until you hear a response.
2) Send an email, continue on your day and handle the response when you get it.

Scenario #1 is synchronous. Scenario #2 is asynchronous.

Here is an example of a synchronous API:

 print('at the beginning');  
 var file = new File('config.txt');  
 var contents = file.readAsStringSync(); // program blocks until all contents are read  
 print(contents);  
 print('at the end');

This program will print:

at the beginning
[config file contents]
at the end

The above code runs as you would expect, line by line. The file contents can be used immediately in the line after readAsStringSync().

However, if the file is large, the entire program is blocked waiting for the file to be read into memory. For simple command-line scripts this is usually acceptable, but for client-side apps or for server programs, blocking is totally not cool. Surely, we can do better!

To write responsive and asynchronous programs, you should not block on work but instead ask to be notified when the work is complete. Here is an example of an asynchronous API:

 print('at the beginning');  
 var file = new File('config.txt');  
 Future future = file.readAsString(); // returns immediately  
 future.then((String contents) {  
  print(contents); // prints only when the file contents are ready  
 });  
 print('at the end');

This program will print:

at the beginning
at the end
[config file contents]

On the first event loop iteration, three things happen:
  1. print 'at the beginning'
  2. queue up work to read the file contents
  3. print 'at the end'
When the file is completely read into memory:
  1. The future's callback is fired with the file contents as the value
As you can see, printing the file contents happens "in the future". The program is not blocked waiting for the file to be read, as demonstrated by 'at the end' printed before the file contents.

As an aside, you could write the code like this:

 print('at the beginning');  
 var file = new File('config.txt');  
 file.readAsString().then((String contents) {  
  print(contents); // prints only when the file contents are ready  
 });  
 print('at the end');

Or even more simply:

 print('at the beginning');  
 var file = new File('config.txt');  
 file.readAsString().then(print);  
 print('at the end');

To summarize, asynchronous programming is the art of not blocking the main thread. Writing an asynchronous program can be tricky, because the program doesn't execute in what seems to be linear order. Strong abstractions and object models can help put an object-oriented interface on top of hard-to-follow asynchronous code.

The dart:async library


To help manage asynchronous programs, Dart bundles the dart:async library. Inside, you will find:

  • Future, for handling values returned later
  • Completer, to help create and finish Futures
  • Timer, for repeating tasks, and tasks scheduled for later
  • Stream, for streams of events
  • StreamController, to help create and manage a stream
Let's take a look at each of these classes.

Future and Completer, aka Producing values from the future


If an asynchronous method or function returns a single value (e.g. readAsString() returns one thing, the file contents), it should return a Future. A Future represents a value not yet available, with the expectation that the value will be available in the future. If a function needs to perform some work before generating a value, the function should return a Future instead of taking a callback parameter.

A Completer can help manage the creation, and completion, of a future value. It is recommended to use a Completer, instead of trying to work with a raw Future.

Here is an example method that uses a Completer to return and complete a Future.

 Future<Account> getAccount(String id) {  
  var completer = new Completer();  
  database.query('SELECT id FROM accounts', (results) {  
   var account = new Account.fromDb(results.first);  
   completer.complete(account);  
  }, (error) => completer.completeError(error));  
  return completer.future;  
 }

(Note, the database API is fictional.)

The database.query() method takes a SQL query and a callback function to handle any results. Thanks to lexical scope, the callback has access to the completer, so it can complete the future with the expected value.

The second callback is run when the database driver encounters an error. Notice how you can complete a Future with an error. If you create a future, be sure to complete it with either a value or an error.

The getAccount() method immediately returns the completer's future, before it queries the database. Sometime in the future, after all the network I/O and database protocol handling, the results are generated and the the completer completes.

When a completer completes, the future generated by the completer gets a value, and code waiting for a value is notified.

A client can use the getAccount() method like this:

 Future future = getAccount('234532');  
 future  
  .then((account) => account.login())  
  .catchError((e) => print(e));

Notice how catchError() is chained off of then(). This works because then() actually returns a Future.

Creating futures with values that exist now


Sometimes, you need to conform a synchronous API to an asynchronous API. That is, you might have a value available right now, however you need to wrap it in a Future. Luckily, there's a constructor for that.

Use new Future.immediate(value) to create a future whose value is available on the next event-loop iteration. Here is an example:

 Future<bool> isOnline() {  
  return new Future.immediate(true);  
 }

It's rare that you have the value immediately available, especially when the API was originally designed to be asynchronous. Another use for immediate is to push the work that would be done on a value to the next event-loop cycle.

Similar to Future.immediate() is Future.of(), which runs a function, collects the result, and makes it available on the next event-loop iteration. Here is an example:

 bool checkConnection() {  
  // ...  
 }  
   
 Future<bool> isOffline() {  
  return new Future.of(checkConnection);  
 }

The function is run now, but the value isn't made available until the next event-loop iteration.

If you have a value available now, but you want to delay the completion of a Future, you can use Future.delayed(). The value is generated now, but the future waits before completing. Here is an example:

 Future simulateNetworkLatency(int delayMillis) {  
  return new Future.delayed(delayMillis, () => makeRandomBytes());  
 }

If an error occurred, and you need to immediately complete a Future with an error, you can use Future.immediateError.

 Future isOnline() {  
  if (!isConnected) {  
   return new Future.immediateError(new StateError('not connected'));  
  } else {  
   return new Future.immediate(true);  
  }  
 }

The above code is rare, most of the time a function that returns a Future is also interacting with an asynchronous API.

Protip: Always return a Future from a method that uses a Future. This allows the calling code to properly catch errors that might occur.

Consuming Futures


The previous section looked at producing a Future, either with a Completer or with the various constructors on Future. This section will focus on consuming Futures produced by an API.

Tip: To learn more about the basics of consuming Futures, read Using Future based APIs from dartlang.org.

For robust synchronous code, you should expect and handle errors. Here is a typical example:


 DatabaseConnection db;  
 try {  
  db = openDatabase();  
  var results = db.query();  
 } catch (e) {  
  print(e);  
 } finally {  
  if (db != null) db.close();  
 }


The intended code runs inside the try block, errors and exceptions are handled inside the catch block, and the finally block is run no matter what.

You can achieve the same type of code organization with Future-based asynchronous code. Here is an example:


 DatabaseConnection db;  
 Future future = openDatabase();  
 future  
  .then((_db) {  
   db = _db;  
   db.query();  
  })  
  .catchError(print)  
  .whenComplete(() => if (db != null) db.close());


In the above example, the intended code runs inside then(), errors and exceptions are handled inside catchError(), and whenComplete() is run no matter what.

It's very important to chain catchError() and whenComplete() from the original future object. Do not do this:


 // bad, don't do this  
 Future future = openDatabase();  
 future.then((_) => /* ... */);  
 // this only catches errors from openDatabase(), not from then()  
 future.catchError(print);


The above example will not catch errors thrown by then(). You must chain then(), catchError(), and whenComplete() to full handle errors.

You can chain Futures if you want them to run in order, one after another. Here is an example:


 db.open()  
  .then((_) => db.nuke())  
  .then((_) => db.save("world", "hello"))  
  .then((_) => db.save("is fun", "dart"))  
  .then((_) => db.getByKey("hello"))  
  .then((value) => query('#text').text = value)  
  .catchError((e) => print(e));


Notice how there is one catchError() at the end of the chain. The last catchError() handles any error or exception thrown from anywhere in the chain.

[Moe coming soon!]

Popular posts from this blog

Lists and arrays in Dart

(This is Part 3 in a series about Dart. Check out Part 2, Function in Dart .) Warning : We expect the Dart libraries to undergo potentially sweeping changes before Dart goes to alpha. This document is relevant as of 2011-12-22. Intro Dart is a "batteries included" effort to help app developers build modern web apps. An important "battery" is the bundled core Dart libraries, providing common and rich functionality. Dart is building a solution for large, complex web apps, and providing well tested, integrated, and common libraries is key to helping a web app developer be more productive out of the box. The Collection libraries are a crucial set of APIs that Dart developers get for free. Much more than simple arrays and maps, the Collection library includes standard ways to filter, iterate, inspect, compose, and sort your data. This post specifically looks at List<E> , Dart's ordered, indexable collection of objects. Aside: The Dart project is lucky
Read more

The 29 Healthiest Foods on the Planet

The 29 Healthiest Foods on the Planet > The following is a "healthy food hot list" consisting of the 29 food that will give you the biggest nutritional bang for you caloric buck, as well as decrease your risk for deadly illnesses like cancer, diabetes and heart disease.
Read more

Converting Array to List in Scala

Now, this has to have a built-in somewhere in Scala , because it just seems too common. So, how to convert an Array to a List in Scala? Why do I need this? I needed to drop to Java for some functionality, which in this case returns an Array. I wanted to get that Array into a List to practice my functional programming skillz. **Update**: I figured out how to convert Arrays to Lists the Scala way. Turns out it's a piece of cake. val myList = List.fromArray(Array("one", "two", "three")) or val myList = Array("one","two","three").elements.toList The call to elements returns an Iterator , and from there you can convert to a List via toList . Nice. Because my first version wasn't actually tail recursive, what follows is a true tail recursive solution, if I were to implement this by hand. The above, built in mechanism is much better, though. object ArrayUtil { def toList[a](array: Array[a]): List[a] = { d
Read more