Skip to main content

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;