PR #35

This document is a preview of merging PR #35 as commit e479d408bd5c0465ed6f8515682bb7d60fa2e089.

Do not reference it as authoritative in any way. Instead, see the living specification at https://github.com/tc39/proposal-cancellation.

Multipage preference

Stage 1 Draft / November 20, 2026

Cancellation

Introduction

This proposal brings a subset of WHATWG DOM's AbortController and AbortSignal into ECMAScript, so that ECMAScript (and other specifications) can use them without depending on the rest of the web platform (in particular EventTarget and DOMException).

For hosts which already provide AbortController and AbortSignal, this proposal preserves their existing API, with the iterator-closing change described below. It also adds AbortSignal.prototype.addAbortCallback (see whatwg/dom#1425). Web-platform-specific behaviour is provided through host hooks:

Hosts may also change the [[Prototype]] of %AbortSignal% and %AbortSignal.prototype% (on the web, to %EventTarget% and %EventTarget.prototype%) and add properties to them, such as onabort and AbortSignal.timeout. See 3.2.

Atomics.waitAsync now accepts an options object with optional timeout and signal properties, allowing an asynchronous wait to be aborted. In addition, Atomics.wait and Atomics.waitAsync now throw a TypeError for timeout values that previously underwent numeric coercion, such as "100", and a RangeError for NaN.

See the proposal repository for background material and discussion.

Editor's Note

Open questions and known deviations from the DOM specification:

  • addAbortCallback returns a disposable registration object whose remove and [Symbol.dispose] properties initially refer to the same method for unregistering the callback. In whatwg/dom#1425, addAbortCallback currently returns undefined.
  • When the signal is already aborted, addAbortCallback calls the callback and then throws the signal's abort reason. In whatwg/dom#1425, it calls the callback and returns normally.
  • The DOM specification iterates over a signal's abort algorithms and then empties the set. Here, the algorithms are removed one at a time as they run, so when an abort callback disposes the registration of a callback which has not yet run, that second callback does not run. The DOM specification does not clearly specify what happens in this case.
  • Unlike other built-ins in this specification, methods and accessors on these objects are enumerable to match the Web IDL conventions which existing implementations follow.
  • AbortSignal.any closes its argument's iterator when it encounters a non-AbortSignal element, following ECMAScript convention. Web IDL's sequence conversion does not close the iterator.
  • DOM can retain its garbage collection rule for dependent signals and its requirement to retain a timeout signal while it has an abort event listener when it adopts these operations. Both rules are consistent with this specification, but neither is needed for aborts to be delivered correctly: when a timeout expires, its signal must be aborted whenever that would be observable, including through abort callbacks or dependent signals.

1 Well-Known Intrinsic Objects

Editor's Note
Only the added rows of Table 1 are shown.
Table 1: Well-Known Intrinsic Objects
Intrinsic Name Global Name ECMAScript Language Association
%AbortCallbackRegistrationPrototype% The prototype of abort callback registration objects (3.5.1)
%AbortController% "AbortController" The AbortController constructor (3.3.1)
%AbortSignal% "AbortSignal" The AbortSignal constructor (3.4.1)

2 Constructor Properties of the Global Object

Editor's Note
Only the added subclauses are shown.

2.1 AbortController ( . . . )

See 3.3.1.

2.2 AbortSignal ( . . . )

See 3.4.1.

3 Cancellation

Editor's Note
This clause is added as a new subclause of 27.

An AbortController and its associated AbortSignal are used to request that one or more ongoing operations be cancelled. The code which starts an operation passes the AbortSignal to it. The AbortController can later be used to abort the signal, and code observing the signal can then stop its work.

Note 1

As with any other object, an implementation may reclaim the memory used by an AbortSignal, its abort algorithms, or its links to other signals whenever doing so has no observable effect.

If a signal can still be aborted, the implementation must preserve every observable effect of that abort. Even if user code has dropped its last reference to the signal, a later abort must still run its registered abort algorithms and, on the web, dispatch its abort event. For example:

  • Once an AbortController is unreachable, nothing can abort its signal. So the signal's abort algorithms can be discarded, and so can the signal once no code can reach it.
  • Suppose AbortSignal.any([longLived, perRequest]) is called once per request. Each resulting dependent signal which no code can reach and which has no abort algorithms or event listeners can be discarded, along with its entry in longLived.[[DependentSignals]], even while longLived is still in use. Otherwise a long-lived signal would accumulate every dependent signal ever created from it.
  • If such a dependent signal has a callback registered with addAbortCallback, aborting one of its sources must still invoke that callback.
  • An entry in a dependent signal's [[SourceSignals]] can be discarded once that source can no longer be aborted.

The DOM garbage collection rule for dependent signals is one way to implement this.

Unlike other built-in objects in this specification, every function-valued data property and every accessor property described in this clause has the attribute [[Enumerable]]: true, except for properties whose key is a Symbol and properties named "constructor".

Note 2

This matches the Web IDL conventions which existing implementations of these classes follow.

3.1 Abstract Operations for AbortSignal Objects

3.1.1 CreateAbortSignal ( realm [ , proto [ , additionalInternalSlotsList ] ] )

The abstract operation CreateAbortSignal takes argument realm (a Realm Record) and optional arguments proto (an Object) and additionalInternalSlotsList (a List of names of internal slots) and returns an AbortSignal. It creates a new AbortSignal which is not aborted. Other specifications may use additionalInternalSlotsList to create AbortSignals with additional internal slots (see 3.2). This operation may be invoked by other specifications. It performs the following steps when called:

  1. If proto is not present, set proto to realm.[[Intrinsics]].[[%AbortSignal.prototype%]].
  2. If additionalInternalSlotsList is not present, set additionalInternalSlotsList to a new empty List.
  3. Let internalSlotsList be « [[AbortReason]], [[AbortAlgorithms]], [[SourceSignals]], [[DependentSignals]] ».
  4. Append to internalSlotsList the internal slot names the host specifies for all AbortSignal instances.
  5. Set internalSlotsList to the list-concatenation of internalSlotsList and additionalInternalSlotsList.
  6. Let signal be OrdinaryObjectCreate(proto, internalSlotsList).
  7. Set signal.[[AbortReason]] to undefined.
  8. Set signal.[[AbortAlgorithms]] to a new empty List.
  9. Set signal.[[SourceSignals]] to not-dependent.
  10. Set signal.[[DependentSignals]] to a new empty List.
  11. Perform HostInitializeAbortSignal(signal, realm).
  12. Return signal.

3.1.2 IsAborted ( signal )

The abstract operation IsAborted takes argument signal (an AbortSignal) and returns a Boolean. This operation may be invoked by other specifications. It performs the following steps when called:

  1. If signal.[[AbortReason]] is undefined, return false.
  2. Return true.

3.1.3 Abort Algorithm Registration Records

An Abort Algorithm Registration Record represents a registration of an algorithm on an AbortSignal.

Abort Algorithm Registration Records have the fields listed in Table 2.

Table 2: Abort Algorithm Registration Record Fields
Field Name Value Meaning
[[Signal]] an AbortSignal or empty The signal on which the algorithm is registered, or empty once the registration has been removed.
[[Algorithm]] an Abstract Closure with no parameters or empty The algorithm to perform when [[Signal]] is aborted, or empty once the registration has been removed.

3.1.4 AddAbortAlgorithm ( signal, algorithm )

The abstract operation AddAbortAlgorithm takes arguments signal (an AbortSignal) and algorithm (an Abstract Closure with no parameters) and returns either an Abort Algorithm Registration Record or already-aborted. It arranges for algorithm to be performed when signal is aborted. algorithm must complete normally. This operation may be invoked by other specifications. It performs the following steps when called:

  1. If IsAborted(signal) is true, return already-aborted.
  2. Let entry be the Abort Algorithm Registration Record { [[Signal]]: signal, [[Algorithm]]: algorithm }.
  3. Append entry to signal.[[AbortAlgorithms]].
  4. Return entry.
Note

If signal is already aborted, algorithm is not registered and will never be performed. Callers usually need to handle that case, either by checking IsAborted(signal) beforehand or by checking for already-aborted.

3.1.5 RemoveAbortAlgorithm ( entry )

The abstract operation RemoveAbortAlgorithm takes argument entry (an Abort Algorithm Registration Record) and returns unused. This operation may be invoked by other specifications. It performs the following steps when called:

  1. Let signal be entry.[[Signal]].
  2. If signal is empty, return unused.
  3. Assert: signal.[[AbortAlgorithms]] contains entry.
  4. Remove entry from signal.[[AbortAlgorithms]].
  5. Set entry.[[Signal]] to empty.
  6. Set entry.[[Algorithm]] to empty.
  7. Return unused.

3.1.6 SignalAbort ( signal, reason )

The abstract operation SignalAbort takes arguments signal (an AbortSignal) and reason (an ECMAScript language value) and returns unused. It aborts signal and any signals which depend on it. If reason is undefined, the abort reason is created by HostCreateAbortError. This operation may be invoked by other specifications, but only with a signal which is not a dependent signal. It performs the following steps when called:

  1. Assert: signal.[[SourceSignals]] is not-dependent.
  2. If IsAborted(signal) is true, return unused.
  3. If reason is undefined, set reason to HostCreateAbortError().
  4. Set signal.[[AbortReason]] to reason.
  5. Let dependentSignalsToAbort be a new empty List.
  6. For each element dependentSignal of signal.[[DependentSignals]], do
    1. If IsAborted(dependentSignal) is false, then
      1. Set dependentSignal.[[AbortReason]] to reason.
      2. Append dependentSignal to dependentSignalsToAbort.
  7. Perform RunAbortSteps(signal).
  8. For each element dependentSignal of dependentSignalsToAbort, do
    1. Perform RunAbortSteps(dependentSignal).
  9. Return unused.
Note

A dependent signal is aborted only through its sources. Because CreateDependentAbortSignal links new signals to the sources of a dependent signal rather than to the dependent signal itself, aborting a dependent signal directly would not abort the signals created from it.

3.1.7 RunAbortSteps ( signal )

The abstract operation RunAbortSteps takes argument signal (an AbortSignal) and returns unused. It performs the following steps when called:

  1. Assert: IsAborted(signal) is true.
  2. Repeat, while signal.[[AbortAlgorithms]] is not empty,
    1. Let entry be the first element of signal.[[AbortAlgorithms]].
    2. Let algorithm be entry.[[Algorithm]].
    3. Perform RemoveAbortAlgorithm(entry).
    4. Perform algorithm().
  3. Perform HostAbortSignalAborted(signal).
  4. Return unused.
Note

By the time a source signal's first abort algorithm runs, every previously unaborted signal that depends on it already has the same abort reason.

Callbacks registered with addAbortCallback and abort algorithms added by host code or other specifications share a single list, so they run interleaved in the order in which they were registered.

Each algorithm is removed before it is performed, so an algorithm removed by an earlier one (for example, by disposing an abort callback registration) is never performed. Disposing the same registration again has no effect.

3.1.8 CreateDependentAbortSignal ( signals, realm [ , proto [ , additionalInternalSlotsList ] ] )

The abstract operation CreateDependentAbortSignal takes arguments signals (a List of AbortSignals) and realm (a Realm Record) and optional arguments proto (an Object) and additionalInternalSlotsList (a List of names of internal slots) and returns an AbortSignal. It returns a new AbortSignal which is aborted when any element of signals is aborted. proto and additionalInternalSlotsList are as in CreateAbortSignal; for example, the web platform uses them to create a TaskSignal. This operation may be invoked by other specifications. It performs the following steps when called:

  1. If proto is not present, set proto to realm.[[Intrinsics]].[[%AbortSignal.prototype%]].
  2. If additionalInternalSlotsList is not present, set additionalInternalSlotsList to a new empty List.
  3. Let resultSignal be CreateAbortSignal(realm, proto, additionalInternalSlotsList).
  4. For each element signal of signals, do
    1. If IsAborted(signal) is true, then
      1. Set resultSignal.[[AbortReason]] to signal.[[AbortReason]].
      2. Return resultSignal.
  5. Set resultSignal.[[SourceSignals]] to a new empty List.
  6. For each element signal of signals, do
    1. If signal.[[SourceSignals]] is not-dependent, let sourceSignals be « signal ».
    2. Else, let sourceSignals be signal.[[SourceSignals]].
    3. For each element sourceSignal of sourceSignals, do
      1. Assert: IsAborted(sourceSignal) is false and sourceSignal.[[SourceSignals]] is not-dependent.
      2. If resultSignal.[[SourceSignals]] does not contain sourceSignal, then
        1. Append sourceSignal to resultSignal.[[SourceSignals]].
        2. Append resultSignal to sourceSignal.[[DependentSignals]].
  7. Return resultSignal.
Note

A dependent signal is linked directly to the non-dependent signals it ultimately depends on, never to another dependent signal, so the chain of signals traversed when aborting is never longer than one link.

For when an implementation can discard dependent signals and the links between signals, see the note in 3.

3.2 Host Integration

The [[Prototype]] internal slots of %AbortSignal% and %AbortSignal.prototype% are host-defined. If the host does not define them, they are %Function.prototype% and %Object.prototype%, respectively. A host which defines them must set them before any ECMAScript code is evaluated in the realm (for example, in the host-defined steps of InitializeHostDefinedRealm). Hosts may also define additional properties on %AbortSignal%, %AbortSignal.prototype%, %AbortController%, and %AbortController.prototype%.

A host may specify additional internal slots for all AbortController instances and for all AbortSignal instances. These slots, along with any passed to CreateAbortSignal or CreateDependentAbortSignal as additionalInternalSlotsList, are allocated when the object is created. The complete list of internal slot names used to create each object must contain no duplicates. The host initializes the slots it specifies for all instances in HostInitializeAbortController and HostInitializeAbortSignal.

Note

On the web platform, %AbortSignal% inherits from %EventTarget% and %AbortSignal.prototype% inherits from %EventTarget.prototype%. The host also defines AbortSignal.prototype.onabort and AbortSignal.timeout.

3.2.1 HostCreateAbortCallbackAlgorithm ( callback )

The host-defined abstract operation HostCreateAbortCallbackAlgorithm takes argument callback (a function object) and returns an Abstract Closure with no parameters. It captures any host context needed to invoke callback.

An implementation of HostCreateAbortCallbackAlgorithm must not evaluate any ECMAScript code. Each time the returned closure is performed, it must synchronously call callback once with undefined as the this value and no arguments. The closure must return unused.

The default implementation of HostCreateAbortCallbackAlgorithm performs the following steps when called:

  1. Return a new Abstract Closure with no parameters that captures callback and performs the following steps when called:
    1. Perform Completion(Call(callback, undefined)).
    2. Return unused.
Note

On the web platform, the host captures the Web IDL callback context at registration. The closure invokes the callback with the "report" exception behaviour, which reports a thrown exception to the global object of the callback's associated realm.

3.2.2 HostCreateAbortError ( )

The host-defined abstract operation HostCreateAbortError takes no arguments and returns an Object. It creates the value used as the abort reason when a signal is aborted without an explicit reason.

An implementation of HostCreateAbortError must conform to the following requirements:

  • It must return a new error object in the current realm each time it is called.
  • The returned object must be initialized such that, with its prototype chain in its initial state, reading its "name" property would return "AbortError".
  • It must not evaluate any ECMAScript code.

The default implementation of HostCreateAbortError performs the following steps when called:

  1. Let error be OrdinaryObjectCreate(%Error.prototype%, « [[ErrorData]] »).
  2. Let message be an implementation-defined String.
  3. Perform CreateNonEnumerableDataPropertyOrThrow(error, "message", message).
  4. Perform CreateNonEnumerableDataPropertyOrThrow(error, "name", "AbortError").
  5. Return error.
Note

On the web platform, the host initializes the associated name and message of a new DOMException. Accessors on DOMException.prototype expose those values.

3.2.3 HostInitializeAbortController ( controller )

The host-defined abstract operation HostInitializeAbortController takes argument controller (an AbortController) and returns unused. It initializes host-defined state on controller in the current realm.

An implementation of HostInitializeAbortController must not evaluate any ECMAScript code or modify the internal slots specified by ECMAScript.

The default implementation of HostInitializeAbortController is to return unused.

Note

Web IDL can use host-specified internal slots for [[Realm]] and [[PrimaryInterface]].

3.2.4 HostInitializeAbortSignal ( signal, realm )

The host-defined abstract operation HostInitializeAbortSignal takes arguments signal (an AbortSignal) and realm (a Realm Record) and returns unused. It initializes host-defined state on signal in realm.

An implementation of HostInitializeAbortSignal must not evaluate any ECMAScript code or modify the internal slots specified by ECMAScript.

The default implementation of HostInitializeAbortSignal is to return unused.

Note

Web IDL can use host-specified internal slots for [[Realm]] and [[PrimaryInterface]]. For example, Request.prototype.clone creates its dependent signal in the request's relevant realm, which can differ from the current realm. On the web platform, the host also initializes the state of an EventTarget, including its event listener list.

3.2.5 HostAbortSignalAborted ( signal )

The host-defined abstract operation HostAbortSignalAborted takes argument signal (an AbortSignal) and returns unused. It is called after all of signal's abort algorithms have been performed.

The default implementation of HostAbortSignalAborted is to return unused.

Note

On the web platform, this fires an event named abort at signal. Listeners for that event run after all abort algorithms (including callbacks registered with addAbortCallback), as they do today.

3.3 AbortController Objects

3.3.1 The AbortController Constructor

The AbortController constructor:

  • is %AbortController%.
  • is the initial value of the "AbortController" property of the global object.
  • creates and initializes a new AbortController when called as a constructor.
  • is not intended to be called as a function and will throw an exception when called in that manner.
  • may be used as the value in an extends clause of a class definition. Subclass constructors that intend to inherit the specified AbortController behaviour must include a super call to the AbortController constructor to create and initialize the subclass instance with the internal state necessary to support the built-in methods of AbortController.prototype.

3.3.1.1 AbortController ( )

This function performs the following steps when called:

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Let internalSlotsList be « [[Signal]] ».
  3. Append to internalSlotsList the internal slot names the host specifies for all AbortController instances.
  4. Let controller be ? OrdinaryCreateFromConstructor(NewTarget, "%AbortController.prototype%", internalSlotsList).
  5. Set controller.[[Signal]] to CreateAbortSignal(the current Realm Record).
  6. Perform HostInitializeAbortController(controller).
  7. Return controller.

3.3.2 Properties of the AbortController Constructor

The AbortController constructor:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has the following properties:

3.3.2.1 AbortController.prototype

The initial value of AbortController.prototype is the AbortController prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

3.3.3 Properties of the AbortController Prototype Object

The AbortController prototype object:

  • is %AbortController.prototype%.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • is an ordinary object.
  • does not have a [[Signal]] internal slot.

3.3.3.1 AbortController.prototype.abort ( [ reason ] )

This method performs the following steps when called:

  1. Let controller be the this value.
  2. Perform ? RequireInternalSlot(controller, [[Signal]]).
  3. Perform SignalAbort(controller.[[Signal]], reason).
  4. Return undefined.
Note

If reason is undefined (including when it is not passed), the signal's abort reason is created by HostCreateAbortError.

3.3.3.2 AbortController.prototype.constructor

The initial value of AbortController.prototype.constructor is %AbortController%.

3.3.3.3 get AbortController.prototype.signal

AbortController.prototype.signal is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let controller be the this value.
  2. Perform ? RequireInternalSlot(controller, [[Signal]]).
  3. Return controller.[[Signal]].

3.3.3.4 AbortController.prototype [ %Symbol.toStringTag% ]

The initial value of the %Symbol.toStringTag% property is the String value "AbortController".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

3.3.4 Properties of AbortController Instances

AbortController instances are ordinary objects that inherit properties from the AbortController prototype object. AbortController instances have the internal slots described in Table 3.

Table 3: Internal Slots of AbortController Instances
Internal Slot Type Description
[[Signal]] an AbortSignal The signal which this controller aborts.

3.4 AbortSignal Objects

3.4.1 The AbortSignal Constructor

The AbortSignal constructor:

  • is %AbortSignal%.
  • is the initial value of the "AbortSignal" property of the global object.
  • throws a TypeError exception when called as a function or as a constructor. AbortSignals are created through AbortController, AbortSignal.abort, AbortSignal.any, or by the host.

3.4.1.1 AbortSignal ( )

This function performs the following steps when called:

  1. Throw a TypeError exception.

3.4.2 Properties of the AbortSignal Constructor

The AbortSignal constructor:

  • has a [[Prototype]] internal slot whose value is host-defined (see 3.2).
  • has the following properties:

3.4.2.1 AbortSignal.abort ( [ reason ] )

This function returns a new AbortSignal which is already aborted. It performs the following steps when called:

  1. Let signal be CreateAbortSignal(the current Realm Record).
  2. If reason is undefined, set reason to HostCreateAbortError().
  3. Set signal.[[AbortReason]] to reason.
  4. Return signal.

3.4.2.2 AbortSignal.any ( signals )

This function returns a new AbortSignal which is aborted when any element of signals is aborted, with the abort reason of the element that caused it to be aborted. It performs the following steps when called:

  1. If signals is not an Object, throw a TypeError exception.
  2. Let iteratorRecord be ? GetIterator(signals, sync).
  3. Let signalsList be a new empty List.
  4. Repeat,
    1. Let next be ? IteratorStepValue(iteratorRecord).
    2. If next is done, then
      1. Return CreateDependentAbortSignal(signalsList, the current Realm Record).
    3. If next is not an Object or next does not have an [[AbortReason]] internal slot, then
      1. Let error be ThrowCompletion(a newly created TypeError object).
      2. Return ? IteratorClose(iteratorRecord, error).
    4. Append next to signalsList.

3.4.2.3 AbortSignal.prototype

The initial value of AbortSignal.prototype is the AbortSignal prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

3.4.3 Properties of the AbortSignal Prototype Object

The AbortSignal prototype object:

  • is %AbortSignal.prototype%.
  • has a [[Prototype]] internal slot whose value is host-defined (see 3.2).
  • is an ordinary object.
  • does not have an [[AbortReason]] internal slot or any of the other internal slots of AbortSignal instances.

3.4.3.1 AbortSignal.prototype.addAbortCallback ( callback )

This method registers callback to be called when the signal is aborted, and returns an abort callback registration object which can be used to unregister the callback. If the signal is already aborted, it instead calls callback immediately and then throws the signal's abort reason. It performs the following steps when called:

  1. Let signal be the this value.
  2. Perform ? RequireInternalSlot(signal, [[AbortReason]]).
  3. If IsCallable(callback) is false, throw a TypeError exception.
  4. Let algorithm be HostCreateAbortCallbackAlgorithm(callback).
  5. Let entry be AddAbortAlgorithm(signal, algorithm).
  6. If entry is already-aborted, then
    1. Perform algorithm().
    2. Throw signal.[[AbortReason]].
  7. Let registration be OrdinaryObjectCreate(%AbortCallbackRegistrationPrototype%, « [[AbortRegistration]] »).
  8. Set registration.[[AbortRegistration]] to entry.
  9. Return registration.
Note

The callback is called with undefined as its this value and with no arguments. Code which needs the abort reason can read it from the signal.

When the signal is already aborted, the callback is called before the abort reason is thrown, so that cleanup the callback performs (such as releasing a resource acquired just before registering it) still happens. An exception thrown by the callback is handled as described in 3.2.1, so in this case the method throws the signal's abort reason even if the callback throws.

Unlike with addEventListener, registering the same function multiple times causes it to be called multiple times. The signal retains the callback until it runs or is unregistered, but does not retain the public registration object, so that object can be collected while the callback is still pending.

3.4.3.2 get AbortSignal.prototype.aborted

AbortSignal.prototype.aborted is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let signal be the this value.
  2. Perform ? RequireInternalSlot(signal, [[AbortReason]]).
  3. Return IsAborted(signal).

3.4.3.3 AbortSignal.prototype.constructor

The initial value of AbortSignal.prototype.constructor is %AbortSignal%.

3.4.3.4 get AbortSignal.prototype.reason

AbortSignal.prototype.reason is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps when called:

  1. Let signal be the this value.
  2. Perform ? RequireInternalSlot(signal, [[AbortReason]]).
  3. Return signal.[[AbortReason]].

3.4.3.5 AbortSignal.prototype.throwIfAborted ( )

This method performs the following steps when called:

  1. Let signal be the this value.
  2. Perform ? RequireInternalSlot(signal, [[AbortReason]]).
  3. If IsAborted(signal) is true, throw signal.[[AbortReason]].
  4. Return undefined.

3.4.3.6 AbortSignal.prototype [ %Symbol.toStringTag% ]

The initial value of the %Symbol.toStringTag% property is the String value "AbortSignal".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

3.4.4 Properties of AbortSignal Instances

AbortSignal instances are ordinary objects that inherit properties from the AbortSignal prototype object. AbortSignal instances have the internal slots described in Table 4. Hosts may create AbortSignal instances with additional internal slots (see 3.2).

Table 4: Internal Slots of AbortSignal Instances
Internal Slot Type Description
[[AbortReason]] an ECMAScript language value The reason the signal was aborted, or undefined if it has not been aborted.
[[AbortAlgorithms]] a List of Abort Algorithm Registration Records The registrations to run in insertion order when the signal is aborted.
[[SourceSignals]] a List of AbortSignals or not-dependent not-dependent if this signal is not a dependent signal. Otherwise, the non-dependent signals which this signal depends on. A dependent signal is one created by CreateDependentAbortSignal from signals none of which were already aborted. A dependent signal created from an empty List of signals has an empty [[SourceSignals]] List, and is never aborted.
[[DependentSignals]] a List of AbortSignals The dependent signals which depend on this signal.

3.5 Abort Callback Registration Objects

An abort callback registration is an object returned by AbortSignal.prototype.addAbortCallback. Disposing it unregisters the corresponding callback. There is no constructor for abort callback registrations.

3.5.1 The %AbortCallbackRegistrationPrototype% Object

The %AbortCallbackRegistrationPrototype% object:

3.5.1.1 %AbortCallbackRegistrationPrototype%.remove ( )

This method unregisters the callback if it has not yet been called. It performs the following steps when called:

  1. Let registration be the this value.
  2. Perform ? RequireInternalSlot(registration, [[AbortRegistration]]).
  3. Perform RemoveAbortAlgorithm(registration.[[AbortRegistration]]).
  4. Return undefined.

3.5.1.2 %AbortCallbackRegistrationPrototype% [ %Symbol.dispose% ] ( )

The initial value of the %Symbol.dispose% property is %AbortCallbackRegistrationPrototype.remove%, defined in 3.5.1.1.

Note

This allows using declarations to scope a callback registration to a block. If signal is already aborted, addAbortCallback closes the connection and throws the abort reason, so the request is never sent:

async function doWork(signal, connection, request) {
  using _ = signal.addAbortCallback(() => connection.close());
  await connection.send(request);
} // the callback is unregistered here

3.5.1.3 %AbortCallbackRegistrationPrototype% [ %Symbol.toStringTag% ]

The initial value of the %Symbol.toStringTag% property is the String value "AbortCallbackRegistration".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

3.5.2 Properties of Abort Callback Registration Instances

Abort callback registrations are ordinary objects that inherit properties from %AbortCallbackRegistrationPrototype%. They have the internal slots described in Table 5.

Table 5: Internal Slots of Abort Callback Registration Instances
Internal Slot Type Description
[[AbortRegistration]] an Abort Algorithm Registration Record The entry returned by AddAbortAlgorithm.

4 Atomics

4.1 Waiter Record

Editor's Note
Only the added field is shown.
Table 6: Waiter Record Fields
Field NameValueMeaning
[[AbortRegistration]] an Abort Algorithm Registration Record or empty The registration for an abortable asynchronous wait. Only the waiting agent accesses this field.

4.2 NotifyWaiter ( waiterList, waiterRecord )

The abstract operation NotifyWaiter takes arguments waiterList (a WaiterList Record) and waiterRecord (a Waiter Record) and returns unused. It performs the following steps when called:

  1. Assert: The surrounding agent is in the critical section for waiterList.
  2. If waiterRecord.[[PromiseCapability]] is blocking, then
    1. Wake the agent whose signifier is waiterRecord.[[AgentSignifier]] from suspension.
    2. NOTE: This causes the agent to resume execution in SuspendThisAgent.
  3. Else if AgentSignifier() is waiterRecord.[[AgentSignifier]], then
    1. Let promiseCapability be waiterRecord.[[PromiseCapability]].
    2. Perform ! Call(promiseCapability.[[Resolve]], undefined, « waiterRecord.[[Result]] »).
    3. Perform ResolveAsyncWaiter(waiterRecord).
  4. Else,
    1. Perform EnqueueResolveInAgentJob(waiterRecord.[[AgentSignifier]], waiterRecord.[[PromiseCapability]], waiterRecord.[[Result]]waiterRecord).
  5. Return unused.
Note

An agent must not access another agent's promise capability in any capacity beyond passing it to the host.

4.3 EnqueueResolveInAgentJob ( agentSignifier, promiseCapability, resolution, waiterRecord )

The abstract operation EnqueueResolveInAgentJob takes arguments agentSignifier (an agent signifier), promiseCapability (a PromiseCapability Record), resolution ("ok" or "timed-out"), and waiterRecord (a Waiter Record) and returns unused. It performs the following steps when called:

  1. Let resolveJob be a new Job Abstract Closure with no parameters that captures agentSignifier, promiseCapability, and resolutionwaiterRecord and performs the following steps when called:
    1. Assert: AgentSignifier() is agentSignifier.
    2. Perform ! Call(promiseCapability.[[Resolve]], undefined, « resolution »).
    3. Perform ResolveAsyncWaiter(waiterRecord).
    4. Return unused.
  2. Let realmInTargetAgent be ! GetFunctionRealm(promiseCapabilitywaiterRecord.[[PromiseCapability]].[[Resolve]]).
  3. Assert: agentSignifierwaiterRecord.[[AgentSignifier]] is realmInTargetAgent.[[AgentSignifier]].
  4. Perform HostEnqueueGenericJob(resolveJob, realmInTargetAgent).
  5. Return unused.

4.4 ResolveAsyncWaiter ( waiterRecord )

The abstract operation ResolveAsyncWaiter takes argument waiterRecord (a Waiter Record) and returns unused. It performs the following steps when called:

  1. Assert: AgentSignifier() is waiterRecord.[[AgentSignifier]].
  2. Let entry be waiterRecord.[[AbortRegistration]].
  3. If entry is not empty, perform RemoveAbortAlgorithm(entry).
  4. Let promiseCapability be waiterRecord.[[PromiseCapability]].
  5. Perform ! Call(promiseCapability.[[Resolve]], undefined, « waiterRecord.[[Result]] »).
  6. Return unused.

4.5 DoWait ( mode, ta, index, value, timeout )

The abstract operation DoWait takes arguments mode (sync or async), ta (an ECMAScript language value), index (an ECMAScript language value), value (an ECMAScript language value), and timeout (an ECMAScript language value) and returns either a normal completion containing either an Object, "not-equal", "timed-out", or "ok", or a throw completion. It performs the following steps when called:

  1. Let taRecord be ? ValidateIntegerTypedArray(ta, true).
  2. Let buffer be taRecord.[[Object]].[[ViewedArrayBuffer]].
  3. If IsSharedArrayBuffer(buffer) is false, throw a TypeError exception.
  4. Let byteIndexInBuffer be ? ValidateAtomicAccess(taRecord, index).
  5. Let elementType be TypedArrayElementType(ta).
  6. Assert: elementType is either bigint64 or int32.
  7. If elementType is bigint64, let expected be ? ToBigInt64(value); else let expected be ? ToInt32(value).
  8. Let timeoutNumber be ? ToNumber(timeout).
  9. If mode is async and timeout is an Object, then
    1. Let timeoutNumber be ? Get(timeout, "timeout").
    2. Let signal be ? Get(timeout, "signal").
  10. Else,
    1. Let timeoutNumber be timeout.
    2. Let signal be undefined.
  11. If timeoutNumber is undefined, set timeoutNumber to +∞𝔽.
  12. If timeoutNumber is not a Number, throw a TypeError exception.
  13. If timeoutNumber is NaN, throw a RangeError exception.
  14. If signal is not undefined, then
    1. Perform ? RequireInternalSlot(signal, [[AbortReason]]).
    2. If IsAborted(signal) is true, throw signal.[[AbortReason]].
  15. If timeoutNumber is either NaN or +∞𝔽, let realTimeout be +∞.
  16. Else if timeoutNumber is -∞𝔽, let realTimeout be 0.
  17. Else, let realTimeout be max(ℝ(timeoutNumber), 0).
  18. If mode is sync and AgentCanSuspend() is false, throw a TypeError exception.
  19. Let block be buffer.[[ArrayBufferData]].
  20. Let waiterList be GetWaiterList(block, byteIndexInBuffer).
  21. If mode is sync, then
    1. Let promiseCapability be blocking.
    2. Let resultObj be undefined.
  22. Else,
    1. Let promiseCapability be ! NewPromiseCapability(%Promise%).
    2. Let resultObj be OrdinaryObjectCreate(%Object.prototype%).
  23. Perform EnterCriticalSection(waiterList).
  24. Let witness be GetValueFromBuffer(buffer, byteIndexInBuffer, elementType, true, seq-cst).
  25. If expected ≠ witness, then
    1. Perform LeaveCriticalSection(waiterList).
    2. If mode is sync, return "not-equal".
    3. Perform ! CreateDataPropertyOrThrow(resultObj, "async", false).
    4. Perform ! CreateDataPropertyOrThrow(resultObj, "value", "not-equal").
    5. Return resultObj.
  26. If realTimeout = 0 and mode is async, then
    1. NOTE: There is no special handling of synchronous immediate timeouts. Asynchronous immediate timeouts have special handling in order to fail fast and avoid unnecessary Promise jobs.
    2. Perform LeaveCriticalSection(waiterList).
    3. Perform ! CreateDataPropertyOrThrow(resultObj, "async", false).
    4. Perform ! CreateDataPropertyOrThrow(resultObj, "value", "timed-out").
    5. Return resultObj.
  27. Let thisAgent be AgentSignifier().
  28. Let now be the time value (UTC) identifying the current time.
  29. Let additionalTimeout be an implementation-defined non-negative mathematical value.
  30. Let timeoutTime be ℝ(now) + realTimeout + additionalTimeout.
  31. NOTE: When realTimeout is +∞, timeoutTime is also +∞.
  32. Let waiterRecord be a new Waiter Record { [[AgentSignifier]]: thisAgent, [[PromiseCapability]]: promiseCapability, [[TimeoutTime]]: timeoutTime, [[Result]]: "ok", [[AbortRegistration]]: empty }.
  33. If signal is not undefined, then
    1. Let algorithm be a new Abstract Closure with no parameters that captures waiterList, waiterRecord, signal, and promiseCapability and performs the following steps when called:
      1. Perform EnterCriticalSection(waiterList).
      2. Let pending be whether waiterList.[[Waiters]] contains waiterRecord.
      3. If pending is true, perform RemoveWaiter(waiterList, waiterRecord).
      4. Perform LeaveCriticalSection(waiterList).
      5. If pending is true, perform ! Call(promiseCapability.[[Reject]], undefined, « signal.[[AbortReason]] »).
      6. Return unused.
    2. Let entry be AddAbortAlgorithm(signal, algorithm).
    3. Assert: entry is an Abort Algorithm Registration Record.
    4. Set waiterRecord.[[AbortRegistration]] to entry.
  34. Perform AddWaiter(waiterList, waiterRecord).
  35. If mode is sync, then
    1. Perform SuspendThisAgent(waiterList, waiterRecord).
  36. Else if timeoutTime is finite, then
    1. Perform EnqueueAtomicsWaitAsyncTimeoutJob(waiterList, waiterRecord).
  37. Perform LeaveCriticalSection(waiterList).
  38. If mode is sync, return waiterRecord.[[Result]].
  39. Perform ! CreateDataPropertyOrThrow(resultObj, "async", true).
  40. Perform ! CreateDataPropertyOrThrow(resultObj, "value", promiseCapability.[[Promise]]).
  41. Return resultObj.
Note

Aborting, notifying, and timing out compete to remove the same waiter from its waiter list. For example, if another agent has already removed the waiter in Atomics.notify, aborting the signal leaves the queued resolution with "ok" in effect. If the abort algorithm removes the waiter first, a subsequent notification does not count it.

additionalTimeout allows implementations to pad timeouts as necessary, such as for reducing power consumption or coarsening timer resolution to mitigate timing attacks. This value may differ from call to call of DoWait.

4.6 Atomics.wait ( ta, index, value, timeout )

This function puts the surrounding agent in a wait queue and suspends it until notified or until the wait times out, returning a String differentiating those cases.

An omitted or undefined timeout specifies an unbounded wait. Otherwise, timeout must be a Number. Passing NaN throws a RangeError.

It performs the following steps when called:

  1. Return ? DoWait(sync, ta, index, value, timeout).

4.7 Atomics.waitAsync ( ta, index, value, timeout )

This function returns an Object with async and value properties. If async is true, value is a Promise that is fulfilled with either "ok" when the calling agent is notified or with "timed-out" when the timeout is reached. Otherwise, async is false and value is either "not-equal" or "timed-out".

The fourth argument may be undefined, a Number (in milliseconds), or an Object with optional "timeout" and "signal" properties. Each option may be omitted or undefined; otherwise, "timeout" must be a Number and "signal" must be an AbortSignal. Passing NaN as the fourth argument or as the "timeout" option throws a RangeError. If the signal is already aborted, this function throws its abort reason. If the signal aborts while the waiter is pending, the returned Promise is rejected with the signal's abort reason.

It performs the following steps when called:

  1. Return ? DoWait(async, ta, index, value, timeout).

Copyright & Software License

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.