Skip to content

Commit a30e05f

Browse files
keithamuskoddsson
andcommitted
reword "signals" to "cancellation signals"
This clarifies and separates them from reactivity Signals Co-authored-by: Kristján Oddsson <[email protected]>
1 parent aaea7b3 commit a30e05f

File tree

1 file changed

+35
-32
lines changed

1 file changed

+35
-32
lines changed

learn/techniques/signals-and-cancellation.md renamed to learn/techniques/using-cancellation-signals.md

+35-32
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,42 @@
11
---
2-
title: Using Signals and Cancellation
2+
title: Using Cancellation Signals
33
order: 2
44
---
55

66
Long running tasks, asynchronous tasks, and operations that have a _set up_ and _tear down_ phase, can make use of a
7-
concept called _cancellation_. If you've used other programming languages you might be familiar with objects like
8-
`CancellationToken` (or [Go's `context`](https://pkg.go.dev/context)) - JavaScript's equivalent is `AbortSignal` which
9-
can be operated with an `AbortController`.
7+
concept called _cancellation signals_. If you've used other programming languages you might be familiar with objects
8+
like `CancellationToken` (or [Go's `context`](https://pkg.go.dev/context)) - JavaScript's equivalent is `AbortSignal`
9+
which can be operated with an `AbortController`.
1010

1111
The `AbortController` & `AbortSignal` APIs can help manage operational "life time". Some examples:
1212

1313
- Long running or asynchronous tasks, for example timers or network fetches
1414
- Overlapping operations, for example cancelling in-flight network fetches to replace them with newer ones
1515
- Set up and tear down, for example a Web Components `connectedCallback` and `disconnectedCallback`
1616

17-
## Signal Controller Pattern
17+
## AbortSignal AbortController Pattern
1818

19-
_Signals_ get given to APIs so they know when to abort. Signals are created by _controllers_ (`new AbortSignal()` will
20-
throw an error). _Controllers_ allow you to make the decision of when a Signal changes. Creating an `AbortController`
21-
will also create a new _Signal_ accessible via `.signal`. Code that has access to the _controller_ can determine when it
22-
should be aborted (by calling `.abort()`), while code that has access to the _signal_ can be notified of the abort. To
23-
make a new `AbortController`, call `new AbortContoller()`. The constructor takes no arguments.
19+
_Cancellation Signals_ get given to APIs so they know when to abort. An `AbortSignal` is created by a _controller_
20+
(`new AbortSignal()` will throw an error). _Controllers_ allow you to make the decision of when a _Cancellation Signal_
21+
changes. Creating an `AbortController` will also create a new `AbortSignal`, accessible via `.signal`. Code that has
22+
access to the _controller_ can determine when it should be aborted (by calling `.abort()`), while code that has access
23+
to the _signal_ can be notified of the abort. To make a new `AbortController`, call `new AbortContoller()`. The
24+
constructor takes no arguments.
2425

25-
A _signals_ `.aborted` property will be `true` if the signal has been aborted - you can periodically check that to stop
26-
any work that is about to be done. `AbortSignal` is also an `EventTarget` - it emits an `abort` event which you can
26+
An `AbortSignal`s `.aborted` property will be `true` if the signal has been aborted - you can periodically check that to
27+
stop any work that is about to be done. `AbortSignal` is also an `EventTarget` - it emits an `abort` event which you can
2728
listen to and invoke your tear down.
2829

2930
You can also create some basic _controller-free signals_ that follow some common patterns. For example
30-
`AbortSignal.timeout(1000)` will create a _signal_ that aborts after 1000ms. These _controller-free signals_ cannot be
31-
manually aborted. However, you can _combine_ controller-free and controllable signals with
31+
`AbortSignal.timeout(1000)` will create a _cancellation signal_ that aborts after 1000ms. These _controller-free
32+
signals_ cannot be manually aborted. However, you can _combine_ controller-free and controllable signals with
3233
`AbortSignal.any([...signals])`.
3334

34-
## Using Signals internally manage your private APIs
35+
## Using Cancellation Signals internally manage your private APIs
3536

36-
_Signals_ can be used to manage internal state that you might have. You can create an `AbortController` as part of your
37-
private state, and make use of _signals_ to control behavior. Consumers of your component won't pass these signals to
38-
you, instead you can use them to track a tasks state internally.
37+
_Cancellation Signals_ can be used to manage internal state that you might have. You can create an `AbortController` as
38+
part of your private state, and make use of _signals_ to control behavior. Consumers of your component won't pass these
39+
signals to you, instead you can use them to track a tasks state internally.
3940

4041
A component with `start()` and `stop()` functions can make the `stop()` function abort the controller, and the `start()`
4142
function create the controller, while checking if the signal has been aborted during an asynchronous loop like so:
@@ -82,14 +83,15 @@ class StopWatchElement extends HTMLElement {
8283
}
8384
```
8485
85-
## Using Signals in your own public APIs
86+
## Using Cancellation Signals in your own public APIs
8687
8788
If you can use a signal as part of your internal state, it might be simpler to provide it as part of the public API. If
88-
you are considering using _signals_ in a public API, it's a good idea to make them an optional part of your API as they
89-
won't always be _needed_.
89+
you are considering using _cancellation signals_ in a public API, it's a good idea to make them an optional part of your
90+
API as they won't always be _needed_.
9091
91-
A component using _signals_ no longer needs separate start & stop methods, instead combining into one and relying on the
92-
signal to know when to stop. This can often simplify code as there is no need to track state across different methods.
92+
A component using _cancellation signals_ no longer needs separate start & stop methods, instead combining into one and
93+
relying on the signal to know when to stop. This can often simplify code as there is no need to track state across
94+
different methods.
9395
9496
```js
9597
class StopWatchElement extends HTMLElement {
@@ -120,14 +122,15 @@ class StopWatchElement extends HTMLElement {
120122
}
121123
```
122124
123-
## Combining multiple Signals
125+
## Combining multiple Cancellation Signals
124126
125-
It's possible to combine multiple sources of signals - for example combining internal and external signals to allow for
126-
multiple flavors of API. Two or more signals can be combined into one using `AbortSignal.any()`, which creates a _new
127-
signal_ that aborts when any of the given _signals_ abort. It's similar to `Promise.any()`, but for Signals.
127+
It's possible to combine multiple sources of _cancellation signals_ - for example combining internal and external
128+
_cancellation signals_ to allow for multiple flavors of API. Two or more _cancellation signals_ can be combined into one
129+
using `AbortSignal.any()`, which creates a _new signal_ that aborts when any of the given _cancellation signals_ abort.
130+
It's similar to `Promise.any()`, but for `AbortSignal`.
128131
129-
A component can provide the more traditional `start()` and `stop()` APIs, as well allowing signals to be passed via
130-
`start({ signal })`. Making use of internal and external signals, with `AbortSignal.any()`:
132+
A component can provide the more traditional `start()` and `stop()` APIs, as well allowing _cancellation signals_ to be
133+
passed via `start({ signal })`. Making use of internal and external _cancellation signals_, with `AbortSignal.any()`:
131134
132135
```js
133136
class StopWatchElement extends HTMLElement {
@@ -172,7 +175,7 @@ class StopWatchElement extends HTMLElement {
172175
}
173176
```
174177
175-
### Using Signals to clean up `disconnectedCallback()`
178+
### Using Cancellation Signals to clean up `disconnectedCallback()`
176179
177180
_Web Components_ that use the `connectedCallback()` lifecycle hook to set things up typically want to tear down those
178181
same things in the `disconnectedCallback()`, but this can sometimes get a little unwieldy. Instead of mirroring
@@ -214,12 +217,12 @@ class StopWatchElement extends HTMLElement {
214217
}
215218
```
216219
217-
### Using signals to cancel old requests
220+
### Using Cancellation Signals to cancel old requests
218221
219222
A common task that components might do is turn a user action into a network fetch. For example a search input might
220223
query the database every time a character is pressed. If the user types into the input fast enough, old network requests
221224
might stay _in-flight_, saturating the network and delaying newer requests from coming in, making the component feel
222-
sluggish. A good way to combat this is to cancel stale requests by using signals:
225+
sluggish. A good way to combat this is to cancel stale requests by using _cancellation signals_:
223226
224227
```js
225228
class SearchInputElement extends HTMLInputElement {

0 commit comments

Comments
 (0)