JobContextBase class abstract

The base of a job context: everything a body does without a state.

Subclass it to add a domain of your own — solo, for example, adds the state and its rules. check is the checkpoint, and it is virtual on purpose: a domain checks more than the cancellation. An override calls super.check(), and calls it first. That is where the cancellation of the job is asked: without it join hands a value to a job already cancelled and uncancellable begins its step on one. And while the core cleans up after the body it throws the cancellation of a cancelled job and a StateError otherwise: the body is gone, and no rule is asked for it any more.

A rule that no longer holds throws a Cancelled with a reason of the engine's own. The body lets it out and cancels itself, and a job whose body cancels itself is cancelled the way Job.cancel cancels it: its children stop and its onCancel callbacks run. The job accepts that cancellation as the throw leaves the body, not before: a body that catches it and goes on is not cancelled. To stop the job whatever the body does, cancel it through cancelOwnJob.

See A rule of your own on the engine page for where check is asked.

Implemented types

• JobContext

Constructors

JobContextBase(JobBase<Object?> owner)

Creates the context owner hands to its body.

Properties

cancellable → bool

Whether the job accepts a cancellation it may refuse, as it was created; an uncancellable section does not change it.

no setter

hashCode → int

The hash code for this object.

no setter, inherited

heldCancellation → Cancelled?

The cancellation an open uncancellable section of this job is holding back, or null.

no setter, override

job → Job<Object?>

The job this context belongs to.

no setter, override

pendingCancel → Cancelled?

The cancellation the job has accepted, or null.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

abandonable<T>(FutureOr<T> action(), {FutureOr<void> dispose(T value)?, FutureOr<void> discard(T value)?}) → Future<T>

Runs action and waits for it, but no longer than this job lives.

override

addCancelCallback(void callback()) → void Function()

Registers callback past the public onCancel: the race inside abandonable needs a raw one, unguarded and removable.

addCleanup(FutureOr<void> disposer(), {required bool always, Object? value}) → void Function()

Puts a registration on the cleanup stack of the owner.

beforeChildStart(JobBase<Object?> child) → Cancelled?

The parent's last word before a child starts.

cancelOwnJob(Cancelled cancelled) → void

Cancels the owner with a cancellation it cannot refuse: the rules of a domain come here, and they cancel a job whatever cancellable says.

check() → void

Gives up if the job was cancelled, or if a rule its engine adds stopped holding.

override

child<T>(Future<T> body(JobContext ctx), {Object? key, String describe()?, Duration? timeout}) → ChildJob<T>

Makes an unstarted child that the engine of this job accepts, for run, start and runAll.

override

createEachJob(Future<void> body(JobContext ctx), {Object? key, String describe()?}) → Job<void>

Creates the unstarted child used by each, named by key and describe.

disown(Object value) → bool

Drops the cleanup registered for value by abandonable, join or run.

override

each<T>(Stream<T> stream, FutureOr<void> onData(JobContext ctx, T event), {Object? key, String describe()?}) → Job<void>

Starts a child job that processes stream one event at a time.

override

enterUncancellable() → void

Opens an uncancellable section on the owner: a rejectable cancellation arriving now is held until the section closes.

join<T>(FutureOr<T> action(), {FutureOr<void> dispose(T value)?, FutureOr<void> discard(T value)?}) → Future<T>

Runs action, waits for all of it, and gives up only afterwards.

override

leaveUncancellable() → void

Closes a section opened by enterUncancellable; the outermost one lets a held cancellation through.

log(Object? message) → void

Hands message to JobObserver.onLog as it is.

override

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

notifyError(Object error, StackTrace stackTrace) → void

Announces error and asks for an answer to it: the observer's onError, then onUnanswered of an observer that is a JobAnswerer, or the zone.

onCancel(void callback()) → void Function()

Registers callback to run the moment the job accepts a cancellation, before the body itself learns about it.

override

onDiscard(FutureOr<void> disposer()) → void Function()

Registers disposer to run unless the job ends Done: when it is cancelled, or fails.

override

onDispose(FutureOr<void> disposer()) → void Function()

Registers disposer to run when the job ends, whatever the outcome.

override

pause([Duration duration = Duration.zero]) → Future<void>

Waits for duration, or until the job is cancelled.

override

run<T>(ChildJob<T> child, {FutureOr<void> dispose(T value)?, FutureOr<void> discard(T value)?}) → Future<T>

Starts child right now, as a child of this job, ahead of whatever an engine would have put it through.

override

runAll<T>(Iterable<ChildJob<T>> children) → Future<List<T>>

Runs children side by side and stops the rest as soon as one of them goes wrong.

override

start(ChildJob<Object?> child) → void

Starts child right now, as a child of this job, and leaves its outcome to whoever holds it.

override

startChild<T>(Job<T> child) → void

Adopts and starts child synchronously.

throwIfCancelled() → void

Throws the cancellation the job has accepted, or the one it ended with: a job an engine finished by hand has no pendingCancel, and its cancellation lives in the outcome alone.

throwIfDisposing(String action) → void

Throws StateError while the core unwinds the cleanup stack.

throwIfFinished(String action) → void

Throws StateError if the job has finished: a context that outlived its job neither writes nor starts anything.

throwIfUnattended(String action) → void

Throws StateError when called from inside this job's own JobContext.unattended work.

toString() → String

A string representation of this object.

inherited

unattended(FutureOr<void> action()) → void

Runs action as work this job does not wait for.

override

uncancellable<T>(FutureOr<T> action()) → Future<T>

Runs action with the cancellation held back, and waits for it.

override

Operators

operator ==(Object other) → bool

The equality operator.

inherited