reef_core/cancel.rs
1//! The cooperative cancellation signal every reef boundary shares.
2//!
3//! [`Token`] is the only cancellation type in reef's public surface. It wraps a
4//! battle-tested implementation rather than reimplementing one: every semantic
5//! below — the atomic cancelled flag, the wakeup of every waiter, and child
6//! derivation from a parent — is delegated, so there is no reef-owned
7//! concurrency to get wrong.
8//!
9//! Wrapping exists for the *dependency*, not for the semantics. The concrete
10//! token comes from a crate at `0.7.x` on its own release cadence, and naming it
11//! in a public trait method would put reef's frozen surface at the mercy of a
12//! `0.7 → 0.8` bump it does not control while also forcing every `tool::Executor`
13//! and `tool::Provider` implementor to add a dependency they never asked for.
14//! ADR-020 records the decision, including why the wrapper
15//! deliberately offers **no** conversion back to the underlying token.
16
17use std::fmt;
18use std::future::Future;
19
20use tokio_util::sync::CancellationToken;
21
22/// A cooperative cancellation signal.
23///
24/// A token is cheap to clone and every clone observes the same cancellation.
25/// [`Token::child_token`] derives a token that cancels when its parent does but
26/// whose own cancellation stays local, which is how a Run scopes a tool batch's
27/// cancellation beneath its own.
28///
29/// Cancellation is one-way and idempotent: once cancelled, a token stays
30/// cancelled and further [`Token::cancel`] calls change nothing.
31///
32/// ```
33/// use reef_core::cancel;
34///
35/// let run = cancel::Token::new();
36/// let batch = run.child_token();
37/// assert!(!batch.is_cancelled());
38///
39/// // Cancelling the child leaves the parent running.
40/// batch.cancel();
41/// assert!(batch.is_cancelled());
42/// assert!(!run.is_cancelled());
43///
44/// // Cancelling the parent reaches every descendant.
45/// let sibling = run.child_token();
46/// run.cancel();
47/// assert!(sibling.is_cancelled());
48/// ```
49#[derive(Clone, Default)]
50pub struct Token(CancellationToken);
51
52impl Token {
53 /// Creates a token that has not been cancelled.
54 #[must_use]
55 pub fn new() -> Self {
56 Self(CancellationToken::new())
57 }
58
59 /// Reports whether cancellation has been requested.
60 #[must_use]
61 pub fn is_cancelled(&self) -> bool {
62 self.0.is_cancelled()
63 }
64
65 /// Requests cancellation for this token and every token derived from it.
66 pub fn cancel(&self) {
67 self.0.cancel();
68 }
69
70 /// Derives a token cancelled by this one but not cancelling it.
71 #[must_use]
72 pub fn child_token(&self) -> Self {
73 Self(self.0.child_token())
74 }
75
76 /// Completes once cancellation has been requested.
77 ///
78 /// The returned future is anonymous on purpose: naming a concrete future
79 /// type here would put the underlying implementation back into the public
80 /// surface that [`Token`] exists to keep it out of. Awaiting it is
81 /// cancel-safe — dropping the future deregisters its waker and observes
82 /// nothing.
83 pub fn cancelled(&self) -> impl Future<Output = ()> + Send + '_ {
84 self.0.cancelled()
85 }
86}
87
88impl fmt::Debug for Token {
89 /// Renders the observable state without naming the wrapped type.
90 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
91 formatter
92 .debug_struct("Token")
93 .field("cancelled", &self.0.is_cancelled())
94 .finish()
95 }
96}
97
98#[cfg(test)]
99#[path = "cancel_tests.rs"]
100mod cancel_tests;