Inconsistent cancel safety documentation

[vilgotf]

When reviewing the cancel safety documentation across Tokio I noticed that there exists multiple versions of what should be a standardized description. For example:

• mpsc::Receiver: This method is cancel safe. If recv is used as the event in a tokio::select! statement and some other branch completes first, it is guaranteed that no messages were received on this channel.
• time::Interval: This method is cancellation safe. If tick is used as the branch in a tokio::select! and another branch completes first, then no tick has been consumed.
• task::JoinHandle: The &mut JoinHandle<T> type is cancel safe. If it is used as the event in a tokio::select! statement and some other branch completes first, then it is guaranteed that the output of the task is not lost.

Suggestion

This method is cancel safe. If used as a branch in tokio::select! and another branch completes first, then [...]

Cancel safety is a property of async functions (technically async blocks), not types, so task::JoinHandle is not really cancel safe. Such notices may still be useful to beginners, however. select should clarify that cancel safety only applies to async functions.

[Darksonn]

I don't think the wording has to be 100% exactly the same every time, as long as its not wrong.

[vilgotf]

Using standardized wording makes the documentation easier to skim. Abberations stick out more as you come to expect not only certain words, but even line lengths.