Impl tokio_util::sync::WaitForCancellationFutureOwned

[NobodyXu]

Signed-off-by: Jiahao XU Jiahao_XU@outlook.com

Motivation

tokio_util::sync::WaitForCancellationFuture takes a reference to the CancellationToken, which is hard to use in structs where you don't want a lifetime.

Solution

tokio_util::sync::WaitForCancellationFutureOwned provides an alternative where CancellationToken is taken by value so that WaitForCancellationFutureOwned does not contain any lifetime (but self-referenced) and can be used without worrying about lifetime.

Alternatives

User use ouroboros to create self-reference struct, but it is not zero-cost.
Other self-reference crates that are zero-cost are experimental (e.g. self-reference).

Or the user can do:

let boxed_fut: Pin<Box<(dyn Future<Output = ()> + Send)>> = Box::pin(async move {
    cancellation_token.cancalled()
});

which isn't zero-cost since it requires one extra allocation and also a pointer to vtable for the trait Future.

User could also uses a SmallBox with pre-allocated space on stack to store the future, though it's more complicated and not zero-cost either (extra pointer to vtable and it might incur heap allocation if the pre-allocated space on stack is too small).

Fixes: #4466

[Darksonn]

I'm rather uncomfortable with adding an implementation that looks like this.

[Darksonn]

Looks good to me. Thanks!