From cef98e25e78b8f9c914fd5fc1fdd7f38433a42bc Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Sat, 18 Mar 2023 22:25:23 +0100 Subject: [PATCH] macros: define cancellation safety (#5525) --- tokio/src/macros/select.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/tokio/src/macros/select.rs b/tokio/src/macros/select.rs index 7ba04a00768..31c9b3ac2e5 100644 --- a/tokio/src/macros/select.rs +++ b/tokio/src/macros/select.rs @@ -131,6 +131,13 @@ /// correctly even if it is restarted while waiting at an `.await`, then it is /// cancellation safe. /// +/// Cancellation safety can be defined in the following way: If you have a +/// future that has not yet completed, then it must be a no-op to drop that +/// future and recreate it. This definition is motivated by the situation where +/// a `select!` is used in a loop. Without this guarantee, you would lose your +/// progress when another branch completes and you restart the `select!` by +/// going around the loop. +/// /// Be aware that cancelling something that is not cancellation safe is not /// necessarily wrong. For example, if you are cancelling a task because the /// application is shutting down, then you probably don't care that partially