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:
Future.then
) also remembers the current zone so that it can later run the callback in that 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.
callback
and returns a function that will execute in this zone. [...] callback
and returns a function that will execute in this zone. [...] callback
and returns a function that will execute in this zone. [...] callback
and returns a function that will execute in this zone. [...] callback
and returns a function that will execute in this zone. [...] callback
and returns a function that will execute in this zone. [...] Future
or Stream
. [...] this
. [...] this
and otherZone
are in the same error zone. [...] line
. [...] action
in this zone. [...] action
with argument1
and argument2
in this zone. [...] action
with argument1
and argument2
in this zone and catches synchronous errors. [...] action
in this zone and catches synchronous errors. [...] action
with argument
in this zone. [...] action
with argument
in this zone and catches synchronous errors. [...] callback
asynchronously in this zone. [...] key
. [...]
© 2012 the Dart project authors
Licensed under the Creative Commons Attribution-ShareAlike License v4.0.
https://api.dartlang.org/stable/2.0.0/dart-async/Zone-class.html