feat(tokio-util): Add CancellationTokenWithReason

[conradludgate]

Motivation

#5249

I wanted a way to propagate a reason to the tasks I am cancelling, eg whether it was via a timeout, or via a termination. As the issue states, Go's context.Context has a WithCancelCause feature that is similar.

For now I am making this as a third party crate, but I felt it was easy enough to suggest upstream. Feel free to bikeshed or reject.

Solution

1. Make cancellation_token/tree_node.rs generic over the cancel reason. Replace is_cancelled: bool with cancelled: Option<T>.
2. Copy cancellation_token.rs to cancellation_token_with_reason.rs and make the necessary changes to support the reason.

[conradludgate]

I'll start the bikeshedding:

1. A feature I would like that I couldn't figure out how to implement is having child tokens have more complex reasons. Eg define fn child_token<U: From<T>>. I think it would require some dynamic dispatch to set the cancelled field.

2. Lots of functions assume CancellationToken as a parameter. It would be nice to decompose a CancellationTokenWithReason into a CancellationToken.

3. If the cancellation reason is actionable, eg start graceful shutdown vs shutdown immediately, it might be necessary to send multiple cancellation signals.

[Darksonn]

Interesting ... I don't love the current API, but I do some sense to it.

If the cancellation reason is actionable, eg start graceful shutdown vs shutdown immediately, it might be necessary to send multiple cancellation signals.

At that point, it sounds like it is out of scope for the token. You can implement it with multiple tokens or a watch channel.

[conradludgate]

At that point, it sounds like it is out of scope for the token. You can implement it with multiple tokens or a watch channel.

Yeah, I agree, it's something that needs to be carefully documented, which I haven't properly done for this feature yet.