Document ordering bwetween future drop and JoinHandle completion

[stepancheg]

Motivation

Consider this code

struct MyFuture;

impl Drop for MyFuture {
  fn drop(&mut self) { println!("A"); }
}

impl Future for MyFuture { ... }


let join_handle = tokio::spawn(MyFuture);
let _ = join_handle.await; // Can be completion or abort
println!("B");

Is it guaranteed that B is always printed after A?

Use case can be this:

let task = spawn({ some work });
task.await;
let task2 = spawn({ some work on the same data });

It would be good to know that destructor of data in the first future (e.g. sending some final message from the destructor) does not intersect with the second task.

After reading the code of tokio, I came to conclusion, it is guaranteed.

Solution

Let's make it formal, so users can rely on this behavior.

[Darksonn]

Thanks for the PR!

[stepancheg]

Updated the PR:

• moved to JoinHandle
• mentioned spawned function in addition to spawned future

[Darksonn]

A few wording nits:

• You always spawn a future.
• The mentioned methods are the only way to observe task completion.

Suggested change

	/// It is guaranteed that the spawned future's or function's destructor has finished
	/// before the task completion is observed, for example,
	/// via [`JoinHandle`] `await` or [`JoinHandle::is_finished`].
	/// It is guaranteed that the destructor of the future has finished
	/// before the task completion is observed via [`JoinHandle`] `await` or
	/// [`JoinHandle::is_finished`].

[stepancheg]

You always spawn a future.

In spawn_blocking, the function is spawned, but the same JoinHandle.

The mentioned methods are the only way to observe task completion.

There's also AbortHandle::is_finished. Probably, I should mention it too.

[Darksonn]

Fair enough there is also spawn_blocking. Perhaps we just say "the destructor of the task".

[stepancheg]

Added reference to AbortHandle::is_finished.

[stepancheg]

Replaced future or function with task.

[stepancheg]

spawned task's destructor -> the destructor of the spawned task

[Darksonn]

If you import AbortHandle into this module, you don't need the explicit link.

Suggested change

	/// [`AbortHandle::is_finished](crate::task::AbortHandle::is_finished).
	/// [`AbortHandle::is_finished`](crate::task::AbortHandle::is_finished).

[stepancheg]

Fixed backtick; if it is imported, unused code warning appears.

[Darksonn]

You can fix the warning by replacing super::AbortHandle with AbortHandle on the relevant method.

[stepancheg]

Done!

[stepancheg]

Removed redundant link to JoinHandle.

[Darksonn]

We can reflow the text a bit nicer. With this, LGTM.

[Darksonn]

Suggested change

	/// It is guaranteed that the destructor of the spawned task has finished
	/// before the task completion is observed
	/// via `JoinHandle` `await`, [`JoinHandle::is_finished`] or [`AbortHandle::is_finished`].
	/// It is guaranteed that the destructor of the spawned task has finished
	/// before task completion is observed via `JoinHandle` `await`,
	/// [`JoinHandle::is_finished`] or [`AbortHandle::is_finished`].

[stepancheg]

Done.