1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
//! The cooperative cancellation signal every reef boundary shares.
//!
//! [`Token`] is the only cancellation type in reef's public surface. It wraps a
//! battle-tested implementation rather than reimplementing one: every semantic
//! below — the atomic cancelled flag, the wakeup of every waiter, and child
//! derivation from a parent — is delegated, so there is no reef-owned
//! concurrency to get wrong.
//!
//! Wrapping exists for the *dependency*, not for the semantics. The concrete
//! token comes from a crate at `0.7.x` on its own release cadence, and naming it
//! in a public trait method would put reef's frozen surface at the mercy of a
//! `0.7 → 0.8` bump it does not control while also forcing every `tool::Executor`
//! and `tool::Provider` implementor to add a dependency they never asked for.
//! ADR-020 records the decision, including why the wrapper
//! deliberately offers **no** conversion back to the underlying token.
use fmt;
use Future;
use CancellationToken;
/// A cooperative cancellation signal.
///
/// A token is cheap to clone and every clone observes the same cancellation.
/// [`Token::child_token`] derives a token that cancels when its parent does but
/// whose own cancellation stays local, which is how a Run scopes a tool batch's
/// cancellation beneath its own.
///
/// Cancellation is one-way and idempotent: once cancelled, a token stays
/// cancelled and further [`Token::cancel`] calls change nothing.
///
/// ```
/// use reef_core::cancel;
///
/// let run = cancel::Token::new();
/// let batch = run.child_token();
/// assert!(!batch.is_cancelled());
///
/// // Cancelling the child leaves the parent running.
/// batch.cancel();
/// assert!(batch.is_cancelled());
/// assert!(!run.is_cancelled());
///
/// // Cancelling the parent reaches every descendant.
/// let sibling = run.child_token();
/// run.cancel();
/// assert!(sibling.is_cancelled());
/// ```
;