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.future
Task.waitAll()
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(), {String? name}): Creates a task with the specified action callback and name.

Properties

exception → ErrorResult?: no setter
hashCode → int: The hash code for this object.
no setterinherited
id → int: Returns a unique integer identifier for the task.
final
isCanceled → bool: Returns true if the task is in the TaskState.cancelled state. ; otherwise, returns false.
no setter
isCompleted → bool: Returns true if the task is in the TaskState.completed state. ; otherwise, returns false.
no setter
isFailed → bool: Returns true if the task is in the TaskState.failed state. ; otherwise, returns false.
no setter
isRunning → bool: Returns true if the task was started and it is not completed; otherwise, returns false.
no setter
isStarted → bool: Returns true if the task was started for execution; 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
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
state → TaskState: Returns task state (TaskState).
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.
inherited
catchError(Function onError, {bool test(Object error)?}) → Future<T>: Handles errors emitted by this Future.
inherited
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() → 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.
inherited
timeout(Duration timeLimit, {FutureOr<T> onTimeout()?}) → Future<T>: Stop waiting for this future after timeLimit has passed.
inherited
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.
inherited

Operators

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

Static Properties

current → AnyTask: Returns the currently running task.
no setter
handleOnExitError ↔ FutureOr<void> Function(Object error, StackTrace? stackTrace)?: Global error handler for tasks onExit handlers.
getter/setter pair

Static Methods

onExit(FutureOr<void> handler(AnyTask task)) → void: Assigns a handler for the current task (Task.current) that will be executed as the last thing before it terminates.
run<T>(FutureOr<T> action(), {String? name}) → Task<T>: Creates and starts a task with the specified action callback and name.
sleep([int milliseconds = 0, CancellationToken? token]) → Future<void>: Allows to switch the event loop context to execute other scheduled code in the microtask and timer queue.
waitAll<T>(List<Task<T>> tasks) → Future<void>