Skip to content

Latest commit

 

History

History
239 lines (198 loc) · 9.7 KB

cancellation.md

File metadata and controls

239 lines (198 loc) · 9.7 KB
Raw

Cancellation

Back to Index

Table of Contents

Class: CancellationTokenSource

Signals a CancellationToken that it should be canceled.

Syntax

export declare class CancellationTokenSource {
    constructor(linkedTokens?: Iterable<CancellationToken>);
    readonly token: CancellationToken;
    cancel(): Promise<void>;
    close(): void;
}

new CancellationTokenSource(linkedTokens?)

Initializes a new instance of a CancellationTokenSource.

  • linkedTokens <Iterable> An optional iterable of tokens to which to link this source.

By supplying a set of linked tokens, you can model a complex cancellation graph that allows you to signal cancellation to various subsets of a more complex asynchronous operation. For example, you can create a cancellation hierarchy where a root CancellationTokenSource can be used to signal cancellation for all asynchronous operations (such as when signing out of an application), with linked CancellationTokenSource children used to signal cancellation for subsets such as fetching pages of asynchronous data or stopping long-running background operations in a Web Worker. You can also create a CancellationTokenSource that is attached to multiple existing tokens, allowing you to aggregate multiple cancellation signals into a single token.

source.token

Gets a CancellationToken linked to this source.

source.cancel()

Cancels the source, returning a Promise that is settled when cancellation has completed. Any registered callbacks are executed in a later turn. If any callback raises an exception, the first such exception can be observed by awaiting the return value of this method.

  • Returns: <Promise> A promise that resolves after all registered callbacks have been executed. If any callback raised an exception, the promise will be rejected with the first exception thrown.

source.close()

Closes the source, preventing the possibility of future cancellation.

Class: CancellationToken

Propagates notifications that operations should be canceled.

Syntax

export declare class CancellationToken {
    constructor(canceled?: boolean);
    static readonly none: CancellationToken;
    static readonly canceled: CancellationToken;
    static from(token: CancellationToken | VSCodeCancellationTokenLike | AbortSignalLike): CancellationToken;
    static race(tokens: Iterable<CancellationToken>): CancellationToken;
    static all(tokens: Iterable<CancellationToken>): CancellationToken;
    readonly cancellationRequested: boolean;
    readonly canBeCanceled: boolean;
    throwIfCancellationRequested(): void;
    register(callback: () => void): CancellationTokenRegistration;
}

new CancellationToken(canceled?)

Initializes a new instance of a CancellationToken.

  • canceled <Boolean> An optional value indicating whether the token is canceled.

CancellationToken.none

Gets a token which will never be canceled.

CancellationToken.canceled

Gets a token that is already canceled.

CancellationToken.from(token)

Adapts a CancellationToken-like primitive from a different library.

CancellationToken.race(tokens)

Returns a CancellationToken that becomes canceled when any of the provided tokens are canceled.

CancellationToken.all(tokens)

Returns a CancellationToken that becomes canceled when all of the provided tokens are canceled.

token.cancellationRequested

Gets a value indicating whether cancellation has been requested.

token.canBeCanceled

Gets a value indicating whether the underlying source can be canceled.

token.throwIfCancellationRequested()

Throws a CancelError if cancellation has been requested.

token.register(callback)

Registers a callback to execute when cancellation is requested.

Class: CancelError

An error thrown when an operation is canceled.

Inheritance hierarchy

Syntax

export declare class CancelError Extends Error {
    constructor(message?: string);
}

new CancelError(message?)

Initializes a new instance of the CancelError class.

  • message <String> An optional message for the error.

Interface: CancellationTokenRegistration

An object used to unregister a callback registered to a CancellationToken.

Syntax

export interface CancellationTokenRegistration {
    unregister(): void;
}

registration.unregister()

Unregisters the callback.

Class: CancellationTokenCountdown

An object that provides a CancellationToken that becomes cancelled when all of its containing tokens are canceled. This is similar to CancellationToken.all, except that you are able to add additional tokens.

Syntax

export declare class CancellationTokenCountdown {
    constructor(iterable?: Iterable<CancellationToken>);
    readonly addedCount: number;
    readonly remainingCount: number;
    readonly token: CancellationToken;
    add(token: CancellationToken): this;
}

new CancellationTokenCountdown(iterable?)

Initializes a new instance of the CancellationTokenCountdown class.

  • iterable <Iterable> An optional iterable of tokens to add to the countdown.

countdown.addedCount

Gets the number of tokens added to the countdown.

countdown.remainingCount

Gets the number of tokens that have not yet been canceled.

countdown.token

Gets the CancellationToken for the countdown.

countdown.add(token)

Adds a CancellationToken to the countdown.

Interface: VSCodeCancellationTokenLike

Describes a foreign cancellation primitive similar to the one provided by vscode for extensions.

Syntax

export interface VSCodeCancellationTokenLike {
    readonly isCancellationRequested: boolean;
    onCancellationRequested(listener: () => any): { dispose(): any; };
}

Interface: AbortSignalLike

Describes a foreign cancellation primitive similar to the one used by the DOM.

Syntax

export interface AbortSignalLike {
    readonly aborted: boolean;
    addEventListener(type: "abort", callback: () => any): any;
}