A zone represents an environment that remains stable across asynchronous calls.

Code is always executed in the context of a zone, available as Zone.current. The initial main function runs in the context of the default zone (Zone.ROOT). Code can be run in a different zone using either runZoned, to create a new zone, or Zone.run to run code in the context of an existing zone likely created using Zone.fork.

Developers can create a new zone that overrides some of the functionality of an existing zone. For example, custom zones can replace of modify the behavior of print, timers, microtasks or how uncaught errors are handled.

The Zone class is not subclassable, but users can provide custom zones by forking an existing zone (usually Zone.current) with a ZoneSpecification. This is similar to creating a new class that extends the base Zone class and that overrides some methods, except without actually creating a new class. Instead the overriding methods are provided as functions that explicitly take the equivalent of their own class, the "super" class and the this object as parameters.

Asynchronous callbacks always run in the context of the zone where they were scheduled. This is implemented using two steps:

  1. the callback is first registered using one of registerCallback, registerUnaryCallback, or registerBinaryCallback. This allows the zone to record that a callback exists and potentially modify it (by returning a different callback). The code doing the registration (e.g., Future.then) also remembers the current zone so that it can later run the callback in that zone.
  2. At a later point the registered callback is run in the remembered zone.

This is all handled internally by the platform code and most users don't need to worry about it. However, developers of new asynchronous operations, provided by the underlying system or through native extensions, must follow the protocol to be zone compatible.

For convenience, zones provide bindCallback (and the corresponding bindUnaryCallback or bindBinaryCallback) to make it easier to respect the zone contract: these functions first invoke the corresponding register functions and then wrap the returned function so that it runs in the current zone when it is later asynchronously invoked.

Constants

ROOT → Zone

The root zone.

_ROOT_ZONE

Static Properties

current → Zone

The zone that is currently active.

read-only

Properties

errorZone → Zone

The error zone is the one that is responsible for dealing with uncaught errors.

read-only
parent → Zone

The parent zone of the this zone.

read-only
hashCode → int

The hash code for this object.

read-only, inherited
runtimeType → Type

A representation of the runtime type of the object.

read-only, inherited

Operators

operator [](Object key) → dynamic

Retrieves the zone-value associated with key.

operator ==(other) → bool

The equality operator.

inherited

Methods

bindBinaryCallback<R, T1, T2>(R action(T1 argument1, T2 argument2), { bool runGuarded: true }) → ZoneBinaryCallback<R, T1, T2>

Equivalent to:

bindCallback<R>(R action(), { bool runGuarded: true }) → ZoneCallback<R>

Equivalent to:

bindUnaryCallback<R, T>(R action(T argument), { bool runGuarded: true }) → ZoneUnaryCallback<R, T>

Equivalent to:

createPeriodicTimer(Duration period, void callback(Timer timer)) → Timer

Creates a periodic Timer where the callback is executed in this zone.

createTimer(Duration duration, void callback()) → Timer

Creates a Timer where the callback is executed in this zone.

errorCallback(Object error, StackTrace stackTrace) → AsyncError

Intercepts errors when added programatically to a Future or Stream.

fork({ZoneSpecification specification, Map zoneValues }) → Zone

Creates a new zone as a child of this.

handleUncaughtError<R>(error, StackTrace stackTrace) → R

Handles uncaught asynchronous errors.

inSameErrorZone(Zone otherZone) → bool

Returns true if this and otherZone are in the same error zone.

print(String line) → void

Prints the given line.

registerBinaryCallback<R, T1, T2>(R callback(T1 arg1, T2 arg2)) → ZoneBinaryCallback<R, T1, T2>

Registers the given callback in this zone.

registerCallback<R>(R callback()) → ZoneCallback<R>

Registers the given callback in this zone.

registerUnaryCallback<R, T>(R callback(T arg)) → ZoneUnaryCallback<R, T>

Registers the given callback in this zone.

run<R>(R action()) → R

Executes action in this zone.

runBinary<R, T1, T2>(R action(T1 argument1, T2 argument2), T1 argument1, T2 argument2) → R

Executes the given action with argument1 and argument2 in this zone.

runBinaryGuarded<R, T1, T2>(R action(T1 argument1, T2 argument2), T1 argument1, T2 argument2) → R

Executes the given action with argument1 and argument2 in this zone and catches synchronous errors.

runGuarded<R>(R action()) → R

Executes the given action in this zone and catches synchronous errors.

runUnary<R, T>(R action(T argument), T argument) → R

Executes the given action with argument in this zone.

runUnaryGuarded<R, T>(R action(T argument), T argument) → R

Executes the given action with argument in this zone and catches synchronous errors.

scheduleMicrotask(void action()) → void

Runs action asynchronously in this zone.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a non-existent method or property is accessed.

inherited
toString() → String

Returns a string representation of this object.

inherited