Skip to main content

Class: CancellationScope

workflow.CancellationScope

In the SDK, Workflows are represented internally by a tree of scopes where the execute function runs in the root scope. Cancellation propagates from outer scopes to inner ones and is handled by catching CancelledFailures thrown by cancellable operations (see below).

Scopes are created using the CancellationScope constructor or the static helper methods cancellable, nonCancellable and withTimeout.

When a CancellationScope is cancelled, it will propagate cancellation any child scopes and any cancellable operations created within it, such as:

  • Activities
  • Child Workflows
  • Timers (created with the sleep function)
  • Triggers

example

await CancellationScope.cancellable(async () => {  const promise = someActivity();  CancellationScope.current().cancel(); // Cancels the activity  await promise; // Throws CancelledFailure});

example

const scope = new CancellationScope();const promise = scope.run(someActivity);scope.cancel(); // Cancels the activityawait promise; // Throws CancelledFailure

Constructors#

constructor#

new CancellationScope(options?)

Parameters#

NameType
options?CancellationScopeOptions

Properties#

cancelRequested#

Readonly cancelRequested: Promise<never>

Rejected when scope cancellation is requested


cancellable#

Readonly cancellable: boolean

If false, prevent outer cancellation from propagating to inner scopes, Activities, timers, and Triggers, defaults to true. (Scope still propagates CancelledFailure thrown from within)


parent#

Optional Readonly parent: CancellationScope

An optional CancellationScope (useful for running background tasks), defaults to CancellationScope.current()

Accessors#

consideredCancelled#

get consideredCancelled(): boolean

Returns#

boolean

Methods#

cancel#

cancel(): void

Request to cancel the scope and linked children

Returns#

void


run#

run<T>(fn): Promise<T>

Activate the scope as current and run fn

Any timers, Activities, Triggers and CancellationScopes created in the body of fn automatically link their cancellation to this scope.

Type parameters#

Name
T

Parameters#

NameType
fn() => Promise<T>

Returns#

Promise<T>

the result of fn


cancellable#

Static cancellable<T>(fn): Promise<T>

Alias to new CancellationScope({ cancellable: true }).run(fn)

Type parameters#

Name
T

Parameters#

NameType
fn() => Promise<T>

Returns#

Promise<T>


current#

Static current(): CancellationScope

Get the current "active" scope

Returns#

CancellationScope


nonCancellable#

Static nonCancellable<T>(fn): Promise<T>

Alias to new CancellationScope({ cancellable: false }).run(fn)

Type parameters#

Name
T

Parameters#

NameType
fn() => Promise<T>

Returns#

Promise<T>


withTimeout#

Static withTimeout<T>(timeout, fn): Promise<T>

Alias to new CancellationScope({ cancellable: true, timeout }).run(fn)

Type parameters#

Name
T

Parameters#

NameType
timeoutnumber
fn() => Promise<T>

Returns#

Promise<T>