JoinSet, clarify behaviour of blocking code under abort/drop #6802
Conversation
I noticed some confusion when users interact with JoinSet. While task::spawn_blocking notes that blocking code can not be aborted that same warning is not present in the JoinSet. While this makes perfect sense when you know how async works in Rust it is difficult for users less experienced with the inner workings of async. Example: RustAudio/rodio#606 (comment)
tokio/src/task/join_set.rs
Outdated
| /// When the `JoinSet` is dropped, all tasks in the `JoinSet` are immediately aborted. | ||
| /// When the `JoinSet` is dropped, all non-blocking tasks in the `JoinSet` are | ||
| /// immediately aborted. Tasks spawned with | ||
| /// [`spawn_blocking`](Self::spawn_blocking) will abort when they reach an | ||
| /// `await` point |
There was a problem hiding this comment.
It doesn't make sense to talk about .await points with spawn_blocking.
You may want to reword these things by referencing the general docs on cancellation of tasks, and by copying the note about spawn_blocking from there into the right spots.
There was a problem hiding this comment.
It doesn't make sense to talk about
.awaitpoints withspawn_blocking.
Ahh yeah ofc, I should have taken the time to look at the definition of spawn_blocking 😅.
by copying the note about spawn_blocking from there into the right spots.
Thats perfect!
Darksonn
added
T-docs
|
Thank you for the PR! |
|
Why does JoinSet::spawn_blocking return a AbortHandle? That seems misleading if the AbortHandle can not actually do anything. |
|
Nevermind I just found it:
Would it be a good idea to call this out in the JoinSet docs, or is that getting too verbose? |
tokio/src/task/join_set.rs
Outdated
| /// When the `JoinSet` is dropped, all tasks in the `JoinSet` are immediately aborted. | ||
| /// When the `JoinSet` is dropped, all *async* tasks in the `JoinSet` are | ||
| /// immediately aborted. Tasks spawned with [`spawn_blocking`] or | ||
| /// [`spawn_blocking_on`] can not be aborted as they are not *async*, see [task | ||
| /// cancellation]. |
There was a problem hiding this comment.
Technically, they are aborted. It just has not effect unless it happens before the spawn_blocking task even starts running.
There was a problem hiding this comment.
Is the window between the task being spawned and it starting execution not extremely small? I fail to see the use case for abort. If I am to document it I would like to mention a case/example which helps the reader understand that window.
There was a problem hiding this comment.
nevermind just thought of it, the executor might have been set up to only allow a few simultaneous blocking tasks or rather threads. Ill work that into the docs
|
anything still blocking this? |
Co-authored-by: Motoyuki Kimura <[email protected]>
| /// When the `JoinSet` is dropped, all *async* tasks in the `JoinSet` are | ||
| /// immediately aborted. Tasks spawned with [`spawn_blocking`] or | ||
| /// [`spawn_blocking_on`] can only be aborted before they start running. | ||
| /// This is because they are not *async*, see [task cancellation]. |
There was a problem hiding this comment.
Why is "async" italic every time? We don't usually do that.
There was a problem hiding this comment.
I wanted to highlight the word to stress that it is the difference between async and blocking tasks that leads to the different behaviour. Its just a formatting thing, if it conflicts with the usual docs style it can be removed.
I noticed some confusion when users interact with JoinSet. While task::spawn_blocking notes that blocking code can not be aborted that same warning is not present in the JoinSet.
While this makes perfect sense when you know how async works in Rust it is difficult for users less experienced with the inner workings of async.
Example: RustAudio/rodio#606 (comment)