Object createTask(dynamic create(TaskSpecification specification, Zone zone), TaskSpecification specification)

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);