Zone class
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:
- 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. - 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 and 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.
Similarly, zones provide bindCallbackGuarded (and the corresponding bindUnaryCallbackGuarded and bindBinaryCallbackGuarded), when the callback should be invoked through Zone.runGuarded.
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
Methods
-
bindBinaryCallback<
R, T1, T2>( R callback(T1 argument1, T2 argument2)) → ZoneBinaryCallback< R, T1, T2> -
Registers the provided
callback
and returns a function that will execute in this zone. [...] -
bindBinaryCallbackGuarded<
T1, T2>( void callback(T1 argument1, T2 argument2)) → void Function(T1, T2) -
Registers the provided
callback
and returns a function that will execute in this zone. [...] -
bindCallback<
R>( R callback()) → ZoneCallback< R> -
Registers the provided
callback
and returns a function that will execute in this zone. [...] -
bindCallbackGuarded(
void callback()) → void Function() -
Registers the provided
callback
and returns a function that will execute in this zone. [...] -
bindUnaryCallback<
R, T>( R callback(T argument)) → ZoneUnaryCallback< R, T> -
Registers the provided
callback
and returns a function that will execute in this zone. [...] -
bindUnaryCallbackGuarded<
T>( void callback(T argument)) → void Function(T) -
Registers the provided
callback
and returns a function that will execute in this zone. [...] -
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 programmatically to a
Future
orStream
. [...] -
fork(
{ZoneSpecification specification, Map zoneValues }) → Zone -
Creates a new zone as a child of
this
. [...] -
handleUncaughtError(
dynamic error, StackTrace stackTrace) → void - Handles uncaught asynchronous errors. [...]
-
inSameErrorZone(
Zone otherZone) → bool -
Returns true if
this
andotherZone
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
withargument1
andargument2
in this zone. [...] -
runBinaryGuarded<
T1, T2>( void action(T1 argument1, T2 argument2), T1 argument1, T2 argument2) → void -
Executes the given
action
withargument1
andargument2
in this zone and catches synchronous errors. [...] -
runGuarded(
void action()) → void -
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
withargument
in this zone. [...] -
runUnaryGuarded<
T>( void action(T argument), T argument) → void -
Executes the given
action
withargument
in this zone and catches synchronous errors. [...] -
scheduleMicrotask(
void callback()) → void -
Runs
callback
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
Operators
-
operator [](
Object key) → dynamic -
Retrieves the zone-value associated with
key
. [...] -
operator ==(
dynamic other) → bool -
The equality operator. [...]
inherited