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

Futures andStreams are the fundamental building blocksof asynchronous programming in Dart. They are supporteddirectly in the language throughasync andasync*functions, and are available to all libraries throughthedart:core library.

This library provides further tools for creating, consumingand transforming futures and streams, as well as direct access toother asynchronous primitives likeTimer,scheduleMicrotask andZone.

To use this library in your code:

import 'dart:async';

Future

A Future object represents a computation whose return valuemight not yet be available.The Future returns the value of the computationwhen it completes at some time in the future.Futures are often used for APIs that are implemented using adifferent thread or isolate (e.g., the asynchronous I/Ooperations ofdart:io or HTTP requests ofdart:html).

Many methods in the Dart libraries returnFutures whenperforming tasks. For example, when binding anHttpServerto a host and port, thebind() 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 runswhen the Future's operation, in this case thebind() method,completes successfully.The value returned by the operationis passed into the callback function.In this example, thebind() method returns the HttpServerobject. The callback function prints one of its properties.Future.catchError registers a callback function thatruns 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 thecontents of a filesuch as mouse clicks, and a stream of byte lists read from a file.The following example opens a file for reading.Stream.listen registers callback functions that runeach time more data is available, an error has occurred, orthe stream has finished.Further functionality is provided onStream, implemented by callingStream.listen to get the actual data.

Stream<List<int>> stream = File('quotes.txt').openRead();stream.transform(utf8.decoder).forEach(print);

This stream emits a sequence of lists of bytes.The program must then handle those lists of bytes in some way.Here, the code uses a UTF-8 decoder (provided in thedart:convert library)to convert the sequence of bytes into a sequenceof Dart strings.

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

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

Other resources

• Thedart:async section of the library tour:A brief overview of asynchronous programming.

• Use Future-Based APIs: A closer look at Futures andhow to use them to write asynchronous Dart code.

• Futures and Error Handling: Everything youwanted to know about handling errors and exceptions when working withFutures (but were afraid to ask).

• The Event Loop and Dart:Learn how Dart handles the event queue and microtask queue, so you canwrite better asynchronous code with fewer surprises.

• test package: Asynchronous Tests: How to test asynchronouscode.

Classes

Completer<T>

A way to produce Future objects and to complete them laterwith a value or error.

EventSink<T>

ASink that supports adding errors.

Future<T>

The result of an asynchronous computation.

FutureOr<T>

A type representing values that are eitherFuture<T> orT.

MultiStreamController<T>

An enhanced stream controller provided byStream.multi.

Stream<T>

A source of asynchronous data events.

StreamConsumer<S>

Abstract interface for a "sink" accepting multiple entire streams.

StreamController<T>

A controller with the stream it controls.

StreamIterator<T>

AnIterator-like interface for the values of aStream.

StreamSink<S>

A object that accepts stream events both synchronously and asynchronously.

StreamSubscription<T>

A subscription on events from aStream.

StreamTransformer<S,T>

Transforms a Stream.

StreamTransformerBase<S,T>

Base class for implementingStreamTransformer.

StreamView<T>

Stream wrapper that only exposes theStream interface.

SynchronousStreamController<T>

A stream controller that delivers its events synchronously.

Timer

A countdown timer that can be configured to fire once or repeatedly.

Zone

A zone represents an environment that remains stable across asynchronouscalls.

ZoneDelegate

An adapted view of the parent zone.

ZoneSpecification

A parameter object with custom zone function handlers forZone.fork.

Extensions

FutureExtensions onFuture<T>

Convenience methods on futures.

FutureIterable onIterable<Future<T>>

FutureRecord2 on (Future<T1>,Future<T2>)

Parallel operations on a record of futures.

FutureRecord3 on (Future<T1>,Future<T2>,Future<T3>)

Parallel operations on a record of futures.

FutureRecord4 on (Future<T1>,Future<T2>,Future<T3>,Future<T4>)

Parallel operations on a record of futures.

FutureRecord5 on (Future<T1>,Future<T2>,Future<T3>,Future<T4>,Future<T5>)

Parallel operations on a record of futures.

FutureRecord6 on (Future<T1>,Future<T2>,Future<T3>,Future<T4>,Future<T5>,Future<T6>)

Parallel operations on a record of futures.

FutureRecord7 on (Future<T1>,Future<T2>,Future<T3>,Future<T4>,Future<T5>,Future<T6>,Future<T7>)

Parallel operations on a record of futures.

FutureRecord8 on (Future<T1>,Future<T2>,Future<T3>,Future<T4>,Future<T5>,Future<T6>,Future<T7>,Future<T8>)

Parallel operations on a record of futures.

FutureRecord9 on (Future<T1>,Future<T2>,Future<T3>,Future<T4>,Future<T5>,Future<T6>,Future<T7>,Future<T8>,Future<T9>)

Parallel operations on a record of futures.

Functions

runZoned<R>(Rbody(), {Map<Object?,Object?>?zoneValues,ZoneSpecification?zoneSpecification,Function?onError})→ R

Runsbody in its own zone.

runZonedGuarded<R>(Rbody(),voidonError(Objecterror,StackTracestack), {Map<Object?,Object?>?zoneValues,ZoneSpecification?zoneSpecification})→ R?

Runsbody in its own error zone.

scheduleMicrotask(voidcallback())→ void

Runs a function asynchronously.

unawaited(Future<void>?future)→ void

Explicitly ignores a future.

Typedefs

ControllerCallback= void Function()

Type of a stream controller'sonListen,onPause andonResumecallbacks.

ControllerCancelCallback=FutureOr<void> Function()

Type of stream controlleronCancel callbacks.

CreatePeriodicTimerHandler=Timer Function(Zoneself,ZoneDelegateparent,Zonezone,Durationperiod,voidf(Timertimer))

The type of a customZone.createPeriodicTimer implementation function.

CreateTimerHandler=Timer Function(Zoneself,ZoneDelegateparent,Zonezone,Durationduration,voidf())

The type of a customZone.createTimer implementation function.

ErrorCallbackHandler=AsyncError? Function(Zoneself,ZoneDelegateparent,Zonezone,Objecterror,StackTrace?stackTrace)

The type of a customZone.errorCallback implementation function.

ForkHandler=Zone Function(Zoneself,ZoneDelegateparent,Zonezone,ZoneSpecification?specification,Map<Object?,Object?>?zoneValues)

The type of a customZone.fork implementation function.

HandleUncaughtErrorHandler= void Function(Zoneself,ZoneDelegateparent,Zonezone,Objecterror,StackTracestackTrace)

The type of a customZone.handleUncaughtError implementation function.

PrintHandler= void Function(Zoneself,ZoneDelegateparent,Zonezone,Stringline)

The type of a customZone.print implementation function.

RegisterBinaryCallbackHandler=ZoneBinaryCallback<R,T1,T2> Function<R,T1,T2>(Zoneself,ZoneDelegateparent,Zonezone,Rf(T1arg1,T2arg2))

The type of a customZone.registerBinaryCallback implementation function.

RegisterCallbackHandler=ZoneCallback<R> Function<R>(Zoneself,ZoneDelegateparent,Zonezone,Rf())

The type of a customZone.registerCallback implementation function.

RegisterUnaryCallbackHandler=ZoneUnaryCallback<R,T> Function<R,T>(Zoneself,ZoneDelegateparent,Zonezone,Rf(Targ))

The type of a customZone.registerUnaryCallback implementation function.

RunBinaryHandler= R Function<R,T1,T2>(Zoneself,ZoneDelegateparent,Zonezone,Rf(T1arg1,T2arg2),T1arg1,T2arg2)

The type of a customZone.runBinary implementation function.

RunHandler= R Function<R>(Zoneself,ZoneDelegateparent,Zonezone,Rf())

The type of a customZone.run implementation function.

RunUnaryHandler= R Function<R,T>(Zoneself,ZoneDelegateparent,Zonezone,Rf(Targ),Targ)

The type of a customZone.runUnary implementation function.

ScheduleMicrotaskHandler= void Function(Zoneself,ZoneDelegateparent,Zonezone,voidf())

The type of a customZone.scheduleMicrotask implementation function.

ZoneBinaryCallback<R,T1,T2>= R Function(T1,T2)

ZoneCallback<R>= R Function()

ZoneUnaryCallback<R,T>= R Function(T)

Exceptions / Errors

AsyncError

An error and a stack trace.

DeferredLoadException

Thrown when a deferred library fails to load.

ParallelWaitError<V,E>

Error thrown when waiting for multiple futures, when some have errors.

TimeoutException

Thrown when a scheduled timeout happens while waiting for an async result.