feat: added spawn_aborting #6224

dev-ardi · 2023-12-18T13:26:42Z

Motivation

#6160

Solution

A wrapper type around the JoinHandle

Darksonn

Hi. Sorry about the delay in reviewing during the christmas holidays.

Darksonn · 2023-12-30T15:03:32Z

tokio-util/src/task/spawn_aborting.rs

+
+use tokio::task::JoinHandle;
+
+use futures_core::Future;


Please import Future from the standard library instead.

Darksonn · 2023-12-30T15:04:42Z

tokio-util/src/task/spawn_aborting.rs

+/// This function spawns a task that aborts on drop instead of lingering.
+pub fn spawn_aborting<F>(future: F) -> DropHandle<F::Output>
+where
+    F: Future + Send + 'static,
+    F::Output: Send + 'static,
+{
+    DropHandle(tokio::spawn(future))
+}


I don't like this name. It sounds like something that would immediately make something abort.

How about spawn_with_drop_handle or spawn_with_abort_handle?

Another possibility is to make this a constructor method. Then you would type DropHandle::spawn.

For API naming, how about using spawn_abortable which aligns with Abortable in future crate.

Hmm, I don't love spawn_abortable, because in Tokio, all spawned tasks are already abortable using JoinHandle::abort(). Naming the function spawn_abortable kind of implies that all other tasks cannot be aborted.

My personal preference would be to make the spawn function a function on the DropHandle type. IMO, we also ought to have a DropHandle::new() constructor that takes a JoinHandle, so that the abort-on-drop behavior can be added to JoinHandles returned by tokio::task::spawn_local or tokio::task::spawn_blocking.

I'd probably recommend an interface that looks sort of like this:

impl<T> DropHandle<T> { pub fn new<T>(task: JoinHandle<T>) -> Self{ Self(task) } pub fn spawn(future: impl Future<Output = T> + Send + 'static) -> DropHandle<T> { Self(tokio::spwan(future)) } }

Darksonn · 2023-12-30T15:06:49Z

tokio-util/src/task/spawn_aborting.rs

+/// This is a wrapper type around JoinHandle that allows it to be dropped.
+#[derive(Debug)]
+pub struct DropHandle<T>(JoinHandle<T>);


This name is okay, but I think there is precedent for the name AbortHandle elsewhere, so we might want to prefer that name.

Actually, we have a type called AbortHandle in Tokio, and that does something else ... so that name doesn't work.

But another option is AbortOnDropHandle. I'll let you pick.

AbortOnDropHandle is uncomfortably verbose, but I think it's the most descriptive name...the name should make it clear what this type actually does.

Darksonn · 2023-12-30T15:09:09Z

tokio-util/src/task/spawn_aborting.rs

+impl<T> Deref for DropHandle<T> {
+    type Target = JoinHandle<T>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl<T> DerefMut for DropHandle<T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.0
+    }
+}


Instead of this, could you add all of the wrapper methods here? You can implement AsRef<JoinHandle> if you like.

It would probably also be nice with a Future implementation so that you can .await a DropHandle.

Darksonn · 2023-12-30T15:11:52Z

It seems like there's a compilation failure in CI:

error: missing documentation for a module
  --> tokio-util/src/task/mod.rs:17:1
   |
17 | pub mod spawn_aborting;
   | ^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: `-D missing-docs` implied by `-D warnings`
   = help: to override `-D warnings` add `#[allow(missing_docs)]`

However, in this case, I think the answer might just be that the module should not be public.

ancorehraq · 2024-01-01T00:08:05Z

Should this be must_use? Something like #[must_use = "future will be dropped immediately if the handle is not used"]

hawkw · 2024-01-23T17:55:19Z

tokio-util/src/task/spawn_aborting.rs

+/// This function spawns a task that aborts on drop instead of lingering.
+pub fn spawn_aborting<F>(future: F) -> DropHandle<F::Output>
+where
+    F: Future + Send + 'static,
+    F::Output: Send + 'static,
+{
+    DropHandle(tokio::spawn(future))
+}


Hmm, I don't love spawn_abortable, because in Tokio, all spawned tasks are already abortable using JoinHandle::abort(). Naming the function spawn_abortable kind of implies that all other tasks cannot be aborted.

My personal preference would be to make the spawn function a function on the DropHandle type. IMO, we also ought to have a DropHandle::new() constructor that takes a JoinHandle, so that the abort-on-drop behavior can be added to JoinHandles returned by tokio::task::spawn_local or tokio::task::spawn_blocking.

I'd probably recommend an interface that looks sort of like this:

impl<T> DropHandle<T> { pub fn new<T>(task: JoinHandle<T>) -> Self{ Self(task) } pub fn spawn(future: impl Future<Output = T> + Send + 'static) -> DropHandle<T> { Self(tokio::spwan(future)) } }

hawkw · 2024-01-23T17:56:10Z

tokio-util/src/task/spawn_aborting.rs

+/// This is a wrapper type around JoinHandle that allows it to be dropped.
+#[derive(Debug)]
+pub struct DropHandle<T>(JoinHandle<T>);


AbortOnDropHandle is uncomfortably verbose, but I think it's the most descriptive name...the name should make it clear what this type actually does.

hawkw · 2024-01-23T18:06:19Z

tokio-util/src/task/spawn_aborting.rs

+
+use futures_core::Future;
+
+/// This is a wrapper type around JoinHandle that allows it to be dropped.


A JoinHandle can already be dropped, just like all other Rust values. So, this documentation, while technically correct, isn't really explaining what this type is actually for. How about something more like this:

Suggested change

/// This is a wrapper type around JoinHandle that allows it to be dropped.

/// A wrapper around a [`tokio::task::JoinHandle`] which [aborts] the task

/// automatically when the handle is dropped.

///

/// [aborts]: tokio::task::JoinHandle::abort

feat: added spawn_aborting

794649f

Darksonn added A-tokio-util Area: The tokio-util crate M-task Module: tokio/task labels Dec 30, 2023

Darksonn reviewed Dec 30, 2023

View reviewed changes

Merge branch 'master' into master

bb34668

hawkw requested changes Jan 23, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: added spawn_aborting #6224

feat: added spawn_aborting #6224

dev-ardi commented Dec 18, 2023

Darksonn left a comment

Darksonn Dec 30, 2023 •

edited

Darksonn Dec 30, 2023

Darksonn Dec 30, 2023

Xuanwo Jan 23, 2024

hawkw Jan 23, 2024

Darksonn Dec 30, 2023

Darksonn Dec 30, 2023

hawkw Jan 23, 2024

Darksonn Dec 30, 2023

Darksonn commented Dec 30, 2023 •

edited

ancorehraq commented Jan 1, 2024

hawkw Jan 23, 2024

hawkw Jan 23, 2024

hawkw Jan 23, 2024


		use futures_core::Future;

		/// This is a wrapper type around JoinHandle that allows it to be dropped.

-/// This is a wrapper type around JoinHandle that allows it to be dropped.
+/// A wrapper around a [`tokio::task::JoinHandle`] which [aborts] the task
+/// automatically when the handle is  dropped.
+///
+/// [aborts]: tokio::task::JoinHandle::abort

feat: added spawn_aborting #6224

Are you sure you want to change the base?

feat: added spawn_aborting #6224

Conversation

dev-ardi commented Dec 18, 2023

Motivation

Solution

Darksonn left a comment

Choose a reason for hiding this comment

Darksonn Dec 30, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Darksonn commented Dec 30, 2023 • edited

ancorehraq commented Jan 1, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Darksonn Dec 30, 2023 •

edited

Darksonn commented Dec 30, 2023 •

edited