Job<T> class abstract interface

A handle to a job: the outcome, the waiting and the cancellation.

Not a Future: a method that starts a job may be called without an await, and the analyzer will not ask for one. Await done or value where you need to, or register a cancellation listener with whenCancelled and one for the end with whenFinished.

A job that ends with Failed and is never observed hands its error to JobAnswerer.onUnanswered of its observer, and without one that answers to the zone that created the job, the way Dart reports an unhandled Future error. Touching done, value or ignoreFailure, or carrying a failure on through then or a handle of shared, counts as observing it; see ignoreFailure.

Implementers

Constructors

Job(Future<T> body(JobContext ctx), {Object? key, String describe()?, bool cancellable = true, Duration? timeout, JobObserver? observer}): Creates a job and starts it on the next microtask.
factory

Properties

done → Future<Outcome<T>>: Completes with the outcome; never throws.
no setter
hashCode → int: The hash code for this object.
no setterinherited
isCancelled → bool: Whether the job has accepted a cancellation, even if the body still runs, or has ended with one.
no setter
isChild → bool: Whether this job was adopted by a parent — through JobContext.run, JobContext.runAll or JobContext.each.
no setter
isFinished → bool: Whether outcome is set.
no setter
isRunning → bool: Whether the body is running or its children are still finishing.
no setter
key → Object?: The key given at creation.
no setter
level → int: Nesting depth: 0 for a root job, parent.level + 1 for a child.
no setter
outcome → Outcome<T>?: The outcome, or null until the job is finished.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
value → Future<T>: Completes with the returned value, or throws Cancelled with the cancellation stack trace, or throws the body's error.
no setter

Methods

cancel({CancelReason reason = const ManualCancelReason()}) → Future<void>: Cancels the job with reason and waits for it to actually finish.
describe() → String: The description given at creation, or an empty string.
ignoreFailure() → void: Tells the core that nobody is interested in this job's failure.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
shared({Object? key, String describe()?, JobObserver? observer}) → Job<T>: Creates a handle that finishes with the outcome of this job and cannot reach it: one branch of a job continued in several.
then<R>(FutureOr<R> onValue(JobContext ctx, T value), {Object? key, String describe()?, JobObserver? observer}) → Job<R>: Creates a job that runs onValue after this job succeeds and cleans up.
toString() → String: A string representation of this object.
inherited
whenCancelled(void callback(Cancelled)) → void Function(): Registers callback for cancellation and returns an unregister function.
whenFinished(void callback(Outcome<T> outcome)) → void Function(): Registers callback for the end of the job and returns an unregister function.

Operators

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

Static Properties

debug ↔ void Function(String message)?: Tracing of the job lifecycle for debugging; null by default.
getter/setter pair
isCancellationError ↔ bool Function(Object error)?: Says which errors an operation throws because the cancellation of its job stopped it, such as the error a migration throws once a token cancelled through JobContext.onCancel stops it.
getter/setter pair

Static Methods

deferred<T>(Future<T> body(JobContext ctx), {Object? key, String describe()?, bool cancellable = true, Duration? timeout, JobObserver? observer}) → DeferredJob<T>: Creates a job that waits to be told to start.
each<E>(Stream<E> stream, FutureOr<void> onData(JobContext ctx, E event), {Object? key, String describe()?, bool cancellable = true, JobObserver? observer}) → Job<void>: Creates a root job that follows stream, one event at a time.
visitErrors(Object error, StackTrace stackTrace, {required void onFailure(Object error, StackTrace stackTrace), void onCancelled(Cancelled cancelled, StackTrace stackTrace)?}) → void: Walks error and hands each failure in it to onFailure and each cancellation to onCancelled, one at a time.