task: add `AbortHandle` type for cancelling tasks in a `JoinSet` #4530

hawkw · 2022-02-23T20:24:48Z

Motivation

Before we stabilize the JoinSet API, we intend to add a method for
individual tasks in the JoinSet to be aborted. Because the
JoinHandles for the tasks spawned on a JoinSet are owned by the
JoinSet, the user can no longer use them to abort tasks on the
JoinSet. Therefore, we need another way to cause a remote abort of a
task on a JoinSet without holding its JoinHandle.

Solution

This branch adds a new AbortHandle type in tokio::task, which
represents the owned permission to remotely cancel a task, but not to
await its output. The AbortHandle type holds an additional reference
to the task cell.

A crate-private method is added to JoinHandle that returns an
AbortHandle for the same task, incrementing its ref count.
AbortHandle provides a single method, AbortHandle::abort(self), that
remotely cancels the task. Dropping an AbortHandle decrements the
task's ref count but does not cancel it. The AbortHandle type is
currently marked as unstable.

The spawning methods on JoinSet are modified to return an
AbortHandle that can be used to cancel the spawned task.

Future Work

Currently, the AbortHandle type is only available in the public
API through a JoinSet. We could also make the
JoinHandle::abort_handle method public, to allow users to use the
AbortHandle type in other contexts. I didn't do that in this PR,
because I wanted to make the API addition as minimal as possible, but we
could make this method public later.
Currently, AbortHandle is not Clone. We could easily make it
Clone by incrementing the task's ref count. Since this adds more trait
impls to the API, we may want to be cautious about this, but I see no
obvious reason we would need to remove a Clone implementation if one
was added...
There's been some discussion of adding a JoinMap type that allows
aborting tasks by key, and manages a hash map of keys to AbortHandles,
and removes the tasks from the map when they complete. This would make
aborting by key much easier, since the user wouldn't have to worry about
keeping the state of the map of abort handles and the tasks actually
active on the JoinSet in sync. After thinking about it a bit, I
thought this is probably best as a tokio-util API --- it can currently
be implemented in tokio-util with the APIs added in tokio in this
PR.
I noticed while working on this that JoinSet::join_one and
JoinSet::poll_join_one return a cancelled JoinError when a task is
cancelled. I'm not sure if I love this behavior --- it seems like it
would be nicer to just skip cancelled tasks and continue polling. But,
there are currently tests that expect a cancelled JoinError to be
returned for each cancelled task, so I didn't want to change it in
this PR. I think this is worth revisiting before stabilizing the API,
though?

carllerche · 2022-02-23T21:11:19Z

Gotta merge master to fix the broken wasm test.

hawkw · 2022-02-23T21:14:10Z

Gotta merge master to fix the broken wasm test.

ah, whoops -- thanks!

Darksonn

Seems reasonable to me.

tokio/src/runtime/task/join.rs

carllerche · 2022-02-24T18:18:34Z

tokio/src/runtime/task/join.rs

@@ -210,6 +210,16 @@ impl<T> JoinHandle<T> {
            }
        }
    }
+
+    /// Returns a new `AbortHandle` that can be used to remotely abort this task.
+    #[cfg(any(tokio_unstable, test))]


Why is this being enabled w/ test? This is not a public API, so it seems ok, but I am not following the thread.

Also, in #4518, I added a cfg_unstable! macro.

The reason it's enabled with cfg(test) is because I added AbortHandle to the task_combinations.rs tasks, where it's kind of tightly-coupled with the rest of the test. That could be cfg flagged, but it would mean filling the test code with a bunch of #[cfg(tokio_unstable)] attributes --- unlike the task.rs tests, we can't just stick #[cfg(tokio_unstable)] on a couple of unit tests and be done.

tokio/src/runtime/task/mod.rs

carllerche · 2022-02-24T18:20:41Z

tokio/src/runtime/tests/task.rs

@@ -78,6 +78,44 @@ fn create_drop2() {
    handle.assert_dropped();
 }

+#[test]
+fn drop_abort_handle1() {


These tests could be marked as #[cfg(tokio_unstable)]. e.g. https://github.com/tokio-rs/tokio/pull/4518/files#diff-88b4b8cbf7c654d7178a01ca42e7b48ceb9810d4309a0111aa3a5753e3a08e4cR521

carllerche

Looks good. I left some nits about pub visibility.

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

Co-authored-by: Alice Ryhl <alice@ryhl.io>

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

hawkw · 2022-02-24T20:31:15Z

@carllerche

Looks good. I left some nits about pub visibility.

I picked up the CI fix, so this should pass now. If you feel good about the visibility situation, a +1 would be nice. :)

## Motivation There's a broken docs link in the docs for `AbortHandle`. Somehow this managed to slip past CI yesterday when #4530 was merged (https://github.com/tokio-rs/tokio/runs/5325278596?check_suite_focus=true) but it's breaking the build now (https://github.com/tokio-rs/tokio/runs/5337182732?check_suite_focus=true) which seems really weird to me, but...whatever... ## Solution This branch fixes the broken link lol. Signed-off-by: Eliza Weisman <eliza@buoyant.io>

## Motivation In many cases, it is desirable to spawn a set of tasks associated with keys, with the ability to cancel them by key. As an example use case for this sort of thing, see Tower's [`ReadyCache` type][1]. Now that PR #4530 adds a way of cancelling tasks in a `tokio::task::JoinSet`, we can implement a map-like API based on the same `IdleNotifiedSet` primitive. ## Solution This PR adds an implementation of a `JoinMap` type to `tokio_util::task`, using the `JoinSet` type from `tokio::task`, the `AbortHandle` type added in #4530, and the new task IDs added in #4630. Individual tasks can be aborted by key using the `JoinMap::abort` method, and a set of tasks whose key match a given predicate can be aborted using `JoinMap::abort_matching`. When tasks complete, `JoinMap::join_one` returns their associated key alongside the output from the spawned future, or the key and the `JoinError` if the task did not complete successfully. Overall, I think the way this works is pretty straightforward; much of this PR is just API boilerplate to implement the union of applicable APIs from `JoinSet` and `HashMap`. Unlike previous iterations on the `JoinMap` API (e.g. #4538), this version is implemented entirely in `tokio_util`, using only public APIs from the `tokio` crate. Currently, the required `tokio` APIs are unstable, but implementing `JoinMap` in `tokio-util` means we will never have to make stability commitments for the `JoinMap` API itself. [1]: https://github.com/tower-rs/tower/blob/master/tower/src/ready_cache/cache.rs Signed-off-by: Eliza Weisman <eliza@buoyant.io>

# 1.18.0 (April 27, 2022) This release adds a number of new APIs in `tokio::net`, `tokio::signal`, and `tokio::sync`. In addition, it adds new unstable APIs to `tokio::task` (`Id`s for uniquely identifying a task, and `AbortHandle` for remotely cancelling a task), as well as a number of bugfixes. ### Fixed - blocking: add missing `#[track_caller]` for `spawn_blocking` ([#4616]) - macros: fix `select` macro to process 64 branches ([#4519]) - net: fix `try_io` methods not calling Mio's `try_io` internally ([#4582]) - runtime: recover when OS fails to spawn a new thread ([#4485]) ### Added - macros: support setting a custom crate name for `#[tokio::main]` and `#[tokio::test]` ([#4613]) - net: add `UdpSocket::peer_addr` ([#4611]) - net: add `try_read_buf` method for named pipes ([#4626]) - signal: add `SignalKind` `Hash`/`Eq` impls and `c_int` conversion ([#4540]) - signal: add support for signals up to `SIGRTMAX` ([#4555]) - sync: add `watch::Sender::send_modify` method ([#4310]) - sync: add `broadcast::Receiver::len` method ([#4542]) - sync: add `watch::Receiver::same_channel` method ([#4581]) - sync: implement `Clone` for `RecvError` types ([#4560]) ### Changed - update `nix` to 0.24, limit features ([#4631]) - update `mio` to 0.8.1 ([#4582]) - macros: rename `tokio::select!`'s internal `util` module ([#4543]) - runtime: use `Vec::with_capacity` when building runtime ([#4553]) ### Documented - improve docs for `tokio_unstable` ([#4524]) - runtime: include more documentation for thread_pool/worker ([#4511]) - runtime: update `Handle::current`'s docs to mention `EnterGuard` ([#4567]) - time: clarify platform specific timer resolution ([#4474]) - signal: document that `Signal::recv` is cancel-safe ([#4634]) - sync: `UnboundedReceiver` close docs ([#4548]) ### Unstable The following changes only apply when building with `--cfg tokio_unstable`: - task: add `task::Id` type ([#4630]) - task: add `AbortHandle` type for cancelling tasks in a `JoinSet` ([#4530], [#4640]) - task: fix missing `doc(cfg(...))` attributes for `JoinSet` ([#4531]) - task: fix broken link in `AbortHandle` RustDoc ([#4545]) - metrics: add initial IO driver metrics ([#4507]) [#4616]: #4616 [#4519]: #4519 [#4582]: #4582 [#4485]: #4485 [#4613]: #4613 [#4611]: #4611 [#4626]: #4626 [#4540]: #4540 [#4555]: #4555 [#4310]: #4310 [#4542]: #4542 [#4581]: #4581 [#4560]: #4560 [#4631]: #4631 [#4582]: #4582 [#4543]: #4543 [#4553]: #4553 [#4524]: #4524 [#4511]: #4511 [#4567]: #4567 [#4474]: #4474 [#4634]: #4634 [#4548]: #4548 [#4630]: #4630 [#4530]: #4530 [#4640]: #4640 [#4531]: #4531 [#4545]: #4545 [#4507]: #4507

# 1.18.0 (April 27, 2022) This release adds a number of new APIs in `tokio::net`, `tokio::signal`, and `tokio::sync`. In addition, it adds new unstable APIs to `tokio::task` (`Id`s for uniquely identifying a task, and `AbortHandle` for remotely cancelling a task), as well as a number of bugfixes. ### Fixed - blocking: add missing `#[track_caller]` for `spawn_blocking` ([#4616]) - macros: fix `select` macro to process 64 branches ([#4519]) - net: fix `try_io` methods not calling Mio's `try_io` internally ([#4582]) - runtime: recover when OS fails to spawn a new thread ([#4485]) ### Added - macros: support setting a custom crate name for `#[tokio::main]` and `#[tokio::test]` ([#4613]) - net: add `UdpSocket::peer_addr` ([#4611]) - net: add `try_read_buf` method for named pipes ([#4626]) - signal: add `SignalKind` `Hash`/`Eq` impls and `c_int` conversion ([#4540]) - signal: add support for signals up to `SIGRTMAX` ([#4555]) - sync: add `watch::Sender::send_modify` method ([#4310]) - sync: add `broadcast::Receiver::len` method ([#4542]) - sync: add `watch::Receiver::same_channel` method ([#4581]) - sync: implement `Clone` for `RecvError` types ([#4560]) ### Changed - update `nix` to 0.24, limit features ([#4631]) - update `mio` to 0.8.1 ([#4582]) - macros: rename `tokio::select!`'s internal `util` module ([#4543]) - runtime: use `Vec::with_capacity` when building runtime ([#4553]) ### Documented - improve docs for `tokio_unstable` ([#4524]) - runtime: include more documentation for thread_pool/worker ([#4511]) - runtime: update `Handle::current`'s docs to mention `EnterGuard` ([#4567]) - time: clarify platform specific timer resolution ([#4474]) - signal: document that `Signal::recv` is cancel-safe ([#4634]) - sync: `UnboundedReceiver` close docs ([#4548]) ### Unstable The following changes only apply when building with `--cfg tokio_unstable`: - task: add `task::Id` type ([#4630]) - task: add `AbortHandle` type for cancelling tasks in a `JoinSet` ([#4530], [#4640]) - task: fix missing `doc(cfg(...))` attributes for `JoinSet` ([#4531]) - task: fix broken link in `AbortHandle` RustDoc ([#4545]) - metrics: add initial IO driver metrics ([#4507]) [#4616]: #4616 [#4519]: #4519 [#4582]: #4582 [#4485]: #4485 [#4613]: #4613 [#4611]: #4611 [#4626]: #4626 [#4540]: #4540 [#4555]: #4555 [#4310]: #4310 [#4542]: #4542 [#4581]: #4581 [#4560]: #4560 [#4631]: #4631 [#4582]: #4582 [#4543]: #4543 [#4553]: #4553 [#4524]: #4524 [#4511]: #4511 [#4567]: #4567 [#4474]: #4474 [#4634]: #4634 [#4548]: #4548 [#4630]: #4630 [#4530]: #4530 [#4640]: #4640 [#4531]: #4531 [#4545]: #4545 [#4507]: #4507 Signed-off-by: Eliza Weisman <eliza@buoyant.io>

This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [tokio](https://tokio.rs) ([source](https://github.com/tokio-rs/tokio)) | dependencies | minor | `1.17.0` -> `1.18.0` | | [tokio](https://tokio.rs) ([source](https://github.com/tokio-rs/tokio)) | dev-dependencies | minor | `1.17.0` -> `1.18.0` | --- ### Release Notes <details> <summary>tokio-rs/tokio</summary> ### [`v1.18.0`](https://github.com/tokio-rs/tokio/releases/tokio-1.18.0) [Compare Source](tokio-rs/tokio@tokio-1.17.0...tokio-1.18.0) ##### 1.18.0 (April 27, 2022) This release adds a number of new APIs in `tokio::net`, `tokio::signal`, and `tokio::sync`. In addition, it adds new unstable APIs to `tokio::task` (`Id`s for uniquely identifying a task, and `AbortHandle` for remotely cancelling a task), as well as a number of bugfixes. ##### Fixed - blocking: add missing `#[track_caller]` for `spawn_blocking` ([#4616](tokio-rs/tokio#4616)) - macros: fix `select` macro to process 64 branches ([#4519](tokio-rs/tokio#4519)) - net: fix `try_io` methods not calling Mio's `try_io` internally ([#4582](tokio-rs/tokio#4582)) - runtime: recover when OS fails to spawn a new thread ([#4485](tokio-rs/tokio#4485)) ##### Added - macros: support setting a custom crate name for `#[tokio::main]` and `#[tokio::test]` ([#4613](tokio-rs/tokio#4613)) - net: add `UdpSocket::peer_addr` ([#4611](tokio-rs/tokio#4611)) - net: add `try_read_buf` method for named pipes ([#4626](tokio-rs/tokio#4626)) - signal: add `SignalKind` `Hash`/`Eq` impls and `c_int` conversion ([#4540](tokio-rs/tokio#4540)) - signal: add support for signals up to `SIGRTMAX` ([#4555](tokio-rs/tokio#4555)) - sync: add `watch::Sender::send_modify` method ([#4310](tokio-rs/tokio#4310)) - sync: add `broadcast::Receiver::len` method ([#4542](tokio-rs/tokio#4542)) - sync: add `watch::Receiver::same_channel` method ([#4581](tokio-rs/tokio#4581)) - sync: implement `Clone` for `RecvError` types ([#4560](tokio-rs/tokio#4560)) ##### Changed - update `mio` to 0.8.1 ([#4582](tokio-rs/tokio#4582)) - macros: rename `tokio::select!`'s internal `util` module ([#4543](tokio-rs/tokio#4543)) - runtime: use `Vec::with_capacity` when building runtime ([#4553](tokio-rs/tokio#4553)) ##### Documented - improve docs for `tokio_unstable` ([#4524](tokio-rs/tokio#4524)) - runtime: include more documentation for thread_pool/worker ([#4511](tokio-rs/tokio#4511)) - runtime: update `Handle::current`'s docs to mention `EnterGuard` ([#4567](tokio-rs/tokio#4567)) - time: clarify platform specific timer resolution ([#4474](tokio-rs/tokio#4474)) - signal: document that `Signal::recv` is cancel-safe ([#4634](tokio-rs/tokio#4634)) - sync: `UnboundedReceiver` close docs ([#4548](tokio-rs/tokio#4548)) ##### Unstable The following changes only apply when building with `--cfg tokio_unstable`: - task: add `task::Id` type ([#4630](tokio-rs/tokio#4630)) - task: add `AbortHandle` type for cancelling tasks in a `JoinSet` ([#4530](tokio-rs/tokio#4530)], \[[#4640](tokio-rs/tokio#4640)) - task: fix missing `doc(cfg(...))` attributes for `JoinSet` ([#4531](tokio-rs/tokio#4531)) - task: fix broken link in `AbortHandle` RustDoc ([#4545](tokio-rs/tokio#4545)) - metrics: add initial IO driver metrics ([#4507](tokio-rs/tokio#4507)) </details> --- ### Configuration 📅 **Schedule**: At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about these updates again. --- - [ ] If you want to rebase/retry this PR, click this checkbox. --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate). Co-authored-by: cabr2-bot <cabr2.help@gmail.com> Reviewed-on: https://codeberg.org/Calciumdibromid/CaBr2/pulls/1327 Reviewed-by: crapStone <crapstone@noreply.codeberg.org> Co-authored-by: Calciumdibromid Bot <cabr2_bot@noreply.codeberg.org> Co-committed-by: Calciumdibromid Bot <cabr2_bot@noreply.codeberg.org>

WilliamVenner · 2023-09-27T09:34:26Z

Hey, is there any concern blocking the introduction of AbortHandle::clone? Is the concern that Tokio may in future decide to make a breaking change internally regarding task ref count? Seeing as AbortHandle is stabilized now(?), is it ok to go ahead?

hawkw · 2023-09-27T17:28:25Z

Hey, is there any concern blocking the introduction of AbortHandle::clone? Is the concern that Tokio may in future decide to make a breaking change internally regarding task ref count? Seeing as AbortHandle is stabilized now(?), is it ok to go ahead?

Hmm, I think it would be fine to add something like that, personally. I'd recommend opening an issue to discuss it, though, in case others have input.

hawkw added A-tokio Area: The main tokio crate M-runtime Module: tokio/runtime M-task Module: tokio/task C-feature-accepted Category: A feature request that has been accepted pending implementation. labels Feb 23, 2022

hawkw requested review from carllerche and Darksonn February 23, 2022 20:24

hawkw self-assigned this Feb 23, 2022

github-actions bot added the R-loom Run loom tests on this PR label Feb 23, 2022

hawkw changed the title ~~task: add an AbortHandle type for cancelling tasks in a JoinSet~~ task: add AbortHandle type for cancelling tasks in a JoinSet Feb 23, 2022

hawkw force-pushed the eliza/abort-handle branch from 23e979d to 437a3a6 Compare February 23, 2022 21:14

Darksonn reviewed Feb 24, 2022

View reviewed changes

tokio/src/runtime/task/join.rs Outdated Show resolved Hide resolved

hawkw mentioned this pull request Feb 24, 2022

task: consider changing JoinSet to not return cancelled JoinErrors #4534

Closed

carllerche reviewed Feb 24, 2022

View reviewed changes

tokio/src/runtime/task/mod.rs Show resolved Hide resolved

carllerche reviewed Feb 24, 2022

View reviewed changes

hawkw mentioned this pull request Feb 24, 2022

task: implement JoinMap #4538

Closed

hawkw and others added 10 commits February 24, 2022 12:29

rt: add internal AbortHandle type

8992cdc

rt: add abort handle to task combination tests

48dbc38

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

rt: make AbortHandle::abort consume self

f18bb86

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

rt: expose JoinHandle with tokio-unstable

87fe715

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

task: add AbortHandle to JoinSet

2a61f48

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

fix missing tokio_unstable docs

87d4ed0

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

fix wasm tests i guess

107f78c

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

+rustfmt

9dac5b6

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

Update tokio/src/runtime/task/join.rs

b6dd2fd

Co-authored-by: Alice Ryhl <alice@ryhl.io>

cleanup feature flags, add abort module

d77c9be

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

hawkw force-pushed the eliza/abort-handle branch from fe8158f to d77c9be Compare February 24, 2022 20:29

carllerche approved these changes Feb 24, 2022

View reviewed changes

hawkw merged commit 8e0e56f into master Feb 24, 2022

hawkw deleted the eliza/abort-handle branch February 24, 2022 21:08

hawkw mentioned this pull request Feb 25, 2022

task: fix broken link in AbortHandle RustDoc #4545

Merged

hawkw mentioned this pull request Apr 25, 2022

util: implement JoinMap #4640

Merged

hawkw mentioned this pull request Apr 27, 2022

tokio: prepare to release v1.18.0 #4641

Merged

SparkyPotato mentioned this pull request Mar 13, 2023

task: make JoinHandle::abort_handle public #5543

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

task: add `AbortHandle` type for cancelling tasks in a `JoinSet` #4530

task: add `AbortHandle` type for cancelling tasks in a `JoinSet` #4530

hawkw commented Feb 23, 2022

carllerche commented Feb 23, 2022

hawkw commented Feb 23, 2022

Darksonn left a comment

carllerche Feb 24, 2022

hawkw Feb 24, 2022

carllerche Feb 24, 2022

carllerche left a comment

hawkw commented Feb 24, 2022

WilliamVenner commented Sep 27, 2023

hawkw commented Sep 27, 2023

task: add AbortHandle type for cancelling tasks in a JoinSet #4530

task: add AbortHandle type for cancelling tasks in a JoinSet #4530

Conversation

hawkw commented Feb 23, 2022

Motivation

Solution

Future Work

carllerche commented Feb 23, 2022

hawkw commented Feb 23, 2022

Darksonn left a comment

Choose a reason for hiding this comment

carllerche Feb 24, 2022

Choose a reason for hiding this comment

hawkw Feb 24, 2022

Choose a reason for hiding this comment

carllerche Feb 24, 2022

Choose a reason for hiding this comment

carllerche left a comment

Choose a reason for hiding this comment

hawkw commented Feb 24, 2022

WilliamVenner commented Sep 27, 2023

hawkw commented Sep 27, 2023

task: add `AbortHandle` type for cancelling tasks in a `JoinSet` #4530

task: add `AbortHandle` type for cancelling tasks in a `JoinSet` #4530