library
dart:async

Support for asynchronous programming, with classes such as Future and Stream.

Understanding Futures and Streams is a prerequisite for writing just about any Dart program.

To use this library in your code:

import 'dart:async';

Future

A Future object represents a computation whose return value might not yet be available. The Future returns the value of the computation when it completes at some time in the future. Futures are often used for potentially lengthy computations such as I/O and interaction with users.

Many methods in the Dart libraries return Futures when performing tasks. For example, when binding an HttpServer to a host and port, the bind() method returns a Future.

 HttpServer.bind('127.0.0.1', 4444)
     .then((server) => print('${server.isBroadcast}'))
     .catchError(print);

Future.then registers a callback function that runs when the Future's operation, in this case the bind() method, completes successfully. The value returned by the operation is passed into the callback function. In this example, the bind() method returns the HttpServer object. The callback function prints one of its properties. Future.catchError registers a callback function that runs if an error occurs within the Future.

Stream

A Stream provides an asynchronous sequence of data. Examples of data sequences include individual events, like mouse clicks, or sequential chunks of larger data, like multiple byte lists with the contents of a file such as mouse clicks, and a stream of byte lists read from a file. The following example opens a file for reading. Stream.listen registers a callback function that runs each time more data is available.

Stream<List<int>> stream = new File('quotes.txt').openRead();
stream.transform(UTF8.decoder).listen(print);

The stream emits a sequence of a list of bytes. The program must interpret the bytes or handle the raw byte data. Here, the code uses a UTF8 decoder (provided in the dart:convert library) to convert the sequence of bytes into a sequence of Dart strings.

Another common use of streams is for user-generated events in a web app: The following code listens for mouse clicks on a button.

querySelector('#myButton').onClick.listen((_) => print('Click.'));

Other resources

Typedefs

ZoneCallback() → dynamic
ZoneUnaryCallback(arg) → dynamic
ZoneBinaryCallback(arg1, arg2) → dynamic
HandleUncaughtErrorHandler(Zone self, ZoneDelegate parent, Zone zone, error, StackTrace stackTrace) → dynamic
RunHandler(Zone self, ZoneDelegate parent, Zone zone, dynamic f()) → dynamic
RunUnaryHandler(Zone self, ZoneDelegate parent, Zone zone, dynamic f(arg), arg) → dynamic
RunBinaryHandler(Zone self, ZoneDelegate parent, Zone zone, dynamic f(arg1, arg2), arg1, arg2) → dynamic
RegisterCallbackHandler(Zone self, ZoneDelegate parent, Zone zone, dynamic f()) → ZoneCallback
RegisterUnaryCallbackHandler(Zone self, ZoneDelegate parent, Zone zone, dynamic f(arg)) → ZoneUnaryCallback
RegisterBinaryCallbackHandler(Zone self, ZoneDelegate parent, Zone zone, dynamic f(arg1, arg2)) → ZoneBinaryCallback
ErrorCallbackHandler(Zone self, ZoneDelegate parent, Zone zone, Object error, StackTrace stackTrace) → AsyncError
ScheduleMicrotaskHandler(Zone self, ZoneDelegate parent, Zone zone, dynamic f()) → void
CreateTimerHandler(Zone self, ZoneDelegate parent, Zone zone, Duration duration, void f()) → Timer
CreatePeriodicTimerHandler(Zone self, ZoneDelegate parent, Zone zone, Duration period, void f(Timer timer)) → Timer
PrintHandler(Zone self, ZoneDelegate parent, Zone zone, String line) → void
ForkHandler(Zone self, ZoneDelegate parent, Zone zone, ZoneSpecification specification, Map zoneValues) → Zone

Functions

scheduleMicrotask(void callback()) → void
Runs a function asynchronously.
runZoned(dynamic body(), {Map zoneValues, ZoneSpecification zoneSpecification, Function onError}) → dynamic
Runs body in its own zone.

Classes

DeferredLibrary
Indicates that loading of libraryName is deferred.
DeferredLoadException
Thrown when a deferred library fails to load.
Future
An object representing a delayed computation.
TimeoutException
Thrown when a scheduled timeout happens while waiting for an async result.
Completer
A way to produce Future objects and to complete them later with a value or error.
Stream
A source of asynchronous data events.
StreamSubscription
A subscritption on events from a Stream.
EventSink
An interface that abstracts creation or handling of Stream events.
StreamView
Stream wrapper that only exposes the Stream interface.
StreamConsumer
Abstract interface for a "sink" accepting multiple entire streams.
StreamSink
A object that accepts stream events both synchronously and asynchronously.
StreamTransformer
The target of a Stream.transform call.
StreamIterator
An Iterator like interface for the values of a Stream.
StreamController
A controller with the stream it controls.
SynchronousStreamController
A stream controller that delivers its events synchronously.
Timer
A count-down timer that can be configured to fire once or repeatedly.
AsyncError
Pair of error and stack trace. Returned by Zone.errorCallback.
ZoneSpecification
This class provides the specification for a forked zone.
ZoneDelegate
This class wraps zones for delegation.
Zone
A Zone represents the asynchronous version of a dynamic extent. Asynchronous callbacks are executed in the zone they have been queued in. For example, the callback of a future.then is executed in the same zone as the one where the then was invoked.

Exceptions / Errors

DeferredLoadException
Thrown when a deferred library fails to load.
TimeoutException
Thrown when a scheduled timeout happens while waiting for an async result.
AsyncError
Pair of error and stack trace. Returned by Zone.errorCallback.