Task<T> class final

A Task is an object representing some operation that will complete in the future.
Tasks are executed asynchronously and cooperatively.
Cooperative multitasking is a concurrency model where tasks voluntarily yield control (using await).

The result of a task execution is the result of computing the value of the task action. It can be either a value or an exception.
The task itself is an object of Future that wraps the result of the computation.
The main difference between the task and the Future is as follows:

The task does not begin executing the computation immediately after it is created.
The task supports delayed start. Or it may never even be started.
After the computation is completed, the task captures the result of the computation.

In case of completion with an exception, the task does not propagate this exception to the unhandled exception handler immediately.
This unobserved exception is stored in the relevant task object instance until it the task is aware that an exception has been observed.
If the task isn not aware that an exception was observed, this exception will be propagated in the task finalizer (Finalizer).
If the finalizer is not executed by runtime (due to Dart SDK limitations), the exception will remain unobserved.
For this reason, due to the limited functionality of the finalizer, it is recommended to always observe task exceptions (detecting, catching, handling).

Exceptions in task can be observed in one of the following ways:

await task
task.result (only after the task is terminated)
task.exception (only after the task is terminated)
task.asStream() (inherited from Future)
task.catchError() (inherited from Future)
task.then() (inherited from Future)
task.timeout() (inherited from Future)
task.whenComplete() (inherited from Future)

It all comes down to the fact that when accessing the _future field of a task, an instance of the Future object is created and at that moment its life cycle begins.

Implemented types

Future<T>

Available extensions

Constructors

Task(FutureOr<T> action(), {bool combineTokens = true, String? name, CancellationToken? token}): Creates a task with the specified callback function and name.

Properties

exception → AsyncError?: Returns the task exception or null.
no setter
hashCode → int: The hash code for this object.
no setterinherited
id → int: Returns a unique integer identifier for the task.
no setter
isCanceled → bool: Returns true if the task status is TaskStatus.canceled; otherwise, returns false.
no setter
isCreated → bool: Returns true if the task status is TaskStatus.created; otherwise, returns false.
no setter
isFailed → bool: Returns true if the task status is TaskStatus.failed; otherwise, returns false.
no setter
isPending → bool: Returns true if the task status is TaskStatus.pending; otherwise, returns false.
no setter
isRunning → bool: Returns true if the task status is TaskStatus.running; otherwise, returns false.
no setter
isSucceeded → bool: Returns true if the task status is TaskStatus.succeeded; otherwise, returns false.
no setter
isTerminated → bool: Returns true if the task was terminated; otherwise, returns false.
no setter
name → String?: Returns the task name.
final
result → T: Returns the task result.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
status → TaskStatus: Returns task status (TaskStatus).
no setter
toJS → JSPromise<T>: Available on Future<T>, provided by the FutureOfJSAnyToJSPromise extension
A JSPromise that either resolves with the result of the completed Future or rejects with an object that contains its error.
no setter
toJS → JSPromise<JSAny?>: Available on Future<void>, provided by the FutureOfVoidToJSPromise extension
A JSPromise that either resolves once this Future completes or rejects with an object that contains its error.
no setter

Methods

asStream() → Stream<T>: Creates a Stream containing the result of this future.
override
catchError(Function onError, {bool test(Object error)?}) → Future<T>: Handles errors emitted by this Future.
override
ignore() → void: Available on Future<T>, provided by the FutureExtensions extension
Completely ignores this future and its result.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
onError<E extends Object>(FutureOr<T> handleError(E error, StackTrace stackTrace), {bool test(E error)?}) → Future<T>: Available on Future<T>, provided by the FutureExtensions extension
Handles errors on this future.
start() → Future<void>: Starts execution of the task.
then<R>(FutureOr<R> onValue(T value), {Function? onError}) → Future<R>: Register callbacks to be called when this future completes.
override
timeout(Duration timeLimit, {FutureOr<T> onTimeout()?}) → Future<T>: Stop waiting for this future after timeLimit has passed.
override
toString() → String: A string representation of this object.
override
whenComplete(FutureOr<void> action()) → Future<T>: Registers a function to be called when this future completes.
override
withCancellation(CancellationToken token) → Task<T>: Waits for the task to complete and returns the result (or error) if the task completes (successfully or with error) before cancellation request; otherwise, throws a CancellationException exception.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

current → AnyTask: Returns the currently running task.
no setter
token → CancellationToken: Returns the cancellation token for the current task.
no setter

Static Methods

delay([int milliseconds = 0, CancellationToken? token]) → Task<void>: Creates a task that will complete successfully after a time delay or will be completed with status TaskStatus.canceled if a cancellation request was initiated before or during the execution of this method.
onExit(FutureOr<void> handler(AnyTask task)) → void: Assigns a handler for the current task that will be executed after the task is terminated.
run<T>(FutureOr<T> action(), {bool combineTokens = true, String? name, CancellationToken? token}) → Task<T>: Creates and starts a task with the specified callback and name.
sleep([int milliseconds = 0, CancellationToken? token]) → Future<void>: Sleeps at specified time in milliseconds, thereby giving up control to the event loop. A CancellationException exception may be thrown if a cancellation request was initiated before or after calling this method.
whenAll<T>(List<Task<T>> tasks, {Progress<({int count, int total})>? progress}) → Task<List<T>>: Performs a wait operation for tasks to complete.
whenAny<T>(List<Task<T>> tasks, {Progress<({int count, int total})>? progress}) → Task<Task<T>>: Performs a wait operation for tasks to complete. As soon as one of the tasks is completed, it will be immediately returned as the result of this method.
whenEach<T>(List<Task<T>> tasks, {Progress<({int count, int total})>? progress}) → Stream<Task<T>>: Returns a Stream to that each Task in the tasks list will be added, in the order in which they were completed (with any status).