Creates a task in the current zone.
A task represents an asynchronous operation or process that reports back through the event loop.
This function allows the zone to intercept the initialization of the task while the runTask function is invoked when the task reports back.
By default, in the root zone, the create
function is invoked with the
specification
as argument. It returns a task object which is used for all
future interactions between the zone and the task. The object is
a unique instance representing the task. It is generally returned to
whoever initiated the task.
For example, the HTML library uses the returned StreamSubscription as
task object when users register an event listener.
Tasks are created when the program starts an operation that reports back through the event loop. For example, a timer or an HTTP request both return through the event loop and are therefore tasks.
If the create
function is not invoked (because a custom zone has
replaced or intercepted it), then the operation is not started. This
means that a custom zone can intercept tasks, like HTTP requests.
A task goes through the following steps:
- a user invokes a library function that should eventually return through
the event loop.
- the library function creates a TaskSpecification that contains the
necessary information to start the operation, and invokes
Zone.current.createTask
with the specification and a create
closure.
The closure, when invoked, uses the specification to start the operation
(usually by interacting with the underlying system, or as a native
extension), and returns a task object that identifies the running task.
- custom zones handle the request and (unless completely intercepted and
aborted), end up calling the root zone's createTask which runs the
provided create
closure, which may have been replaced at this point.
- later, the asynchronous operation returns through the event loop.
It invokes Zone.runTask on the zone in which the task should run
(and which was originally passed to the create
function by
createTask
). The runTask function receives the
task object, a run
function and an argument. As before, custom zones
may intercept this call. Eventually (unless aborted), the run
function
is invoked. This last step may happen multiple times for tasks that are
not oneshot tasks (see ZoneSpecification.isOneShot
).
Custom zones may replace the specification
with a different one, thus
modifying the task parameters. An operation that wishes to be an
interceptable task must publicly specify the types that intercepting code
sees:
- The specification type (extending TaskSpecification) which holds the
information available when intercepting the createTask
call.
- The task object type, returned by createTask
and create
. This object
may simply be typed as Object.
- The argument type, if runTask takes a meaningful argument.
Experimental. Might disappear without notice.
Source
Object/*=T*/ createTask/*<T, S extends TaskSpecification>*/( /*=T*/ create(TaskSpecification/*=S*/ specification, Zone zone), TaskSpecification/*=S*/ specification);