feat: added spawn_aborting

[dev-ardi]

Motivation

#6160

Solution

A wrapper type around the JoinHandle

[Darksonn]

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

[Darksonn]

Please import Future from the standard library instead.

[Darksonn]

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?

[Darksonn]

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

[Xuanwo]

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

[hawkw]

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]

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

[Darksonn]

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.

[hawkw]

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]

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]

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]

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

[hawkw]

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]

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]

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

[Darksonn]

This feature was added in #6786.