macros: define cancellation safety

[Darksonn]

This adds a precise definition of cancellation safety to the docs of select!.

cc @yoshuawuyts

[satakuma]

If this definition ought to be very precise, I would probably refrain from defining it through the observable effects of future drop + recreate. For example, I would say the following future is cancellation safe under this definition, but just dropping it halfway through the download without driving to the completion can leak disk space:

async fn download_and_verify() -> Sha256Sum {
    for i in 0..N {
        if !is_chunk_downloaded(i) {
            download_data_chunk(i).await;
        }
    }
    let sha_sum = compute_hash();
    delete_all_data_chunks();
    sha_sum
}

In my opinion, it is not safe to use this future inside the select! macro, please let me know if you agree.

[Darksonn]

How would you define it? Inserting a drop-and-recreate of your future in the middle of a program does change what it does, so in some sense it is not a no-op, even if the difference is not observable until later.

[satakuma]

True, I agree that it may not be considered as a no-op.

I was going to say that I would define it like this: “a future is cancellation safe if and only if creating it and dropping before completion is a no-op”. Now that I think of it, it does not account for losing a place in a fair queue, for example in Mutex::lock.

Maybe the definition should be more rigorous and state that both create-and-drop and drop-and-recreate should be no-ops (with “no-op” meaning “no observable effects”)? I am not sure.

[Darksonn]

I expanded a bit, but I think it's fine as-is.