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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
//! Cancellation: how a caller stops a computation that is already running.
//!
//! A long call into this library is one uninterruptible unit of work to the
//! program that made it. That is invisible from Rust, where the caller chose
//! to block, and it is a defect from an embedder that handles signals itself:
//! CPython records SIGINT and runs the handler at its next bytecode boundary,
//! so a Ctrl-C during a multi-minute conversion is delivered only once the
//! conversion returns. The user sees a session that ignores Ctrl-C
//! (`docs/record/python-and-sage-interop.md`).
//!
//! The kernel cannot ask CPython anything — it does not depend on it
//! (`docs/policies/python.md`, P3). So the embedder installs a checker and the
//! kernel calls it:
//!
//! ```text
//! set_checker(f) -> poll() consults f -> panics with Interrupted
//! catch_interrupt(|| .. compute ..) -> Ok(answer) or Err(Interrupted)
//! ```
//!
//! [`poll`] is called from loops whose trip count grows with the input. Where
//! nothing is installed it is one relaxed load and a predictable branch, which
//! is what keeps it affordable in a hot loop.
//!
//! ## Why a panic and not a return value
//!
//! The same constraint that produced the overflow counter in
//! [`guard`](crate::guard) produces this: `Ring::mul` returns `Self`, so
//! generic code has no per-operation failure channel to thread a cancellation
//! through. Every alternative reaches the same place — either every loop that
//! can run long returns `Option`, and every caller of those loops does too, or
//! the stack is unwound. Unwinding is the smaller change and the one that
//! reaches the generic interiors at all.
//!
//! This is the one panic in the crate that is **not** a violated contract
//! (`docs/policies/failure.md`, R2 and the cancellation row of its table). It
//! is raised only when a checker the embedder installed says so, it carries a
//! payload no other panic uses, and the embedder that installed the checker is
//! the one that catches it. A caller who installs nothing cannot reach it.
//!
//! Two things in the crate already behave correctly under it, and neither was
//! written for this:
//!
//! - `escalate` in [`python`](crate::python) tests for `None`, so a panic
//! passes through it rather than being read as overflow. An interrupted
//! fixed-width pass does not silently restart over `BigInt`.
//! - `src/memo.rs` runs `compute` outside its guard and clears lock poison
//! rather than propagating it, so an unwind through a cache leaves no
//! half-built entry and does not disable the table for later calls.
//!
//! ## Which thread may poll
//!
//! Only the thread that entered the library. A cancellation unwinds the thread
//! that saw it, and a worker's unwind is not the caller's: the parallel
//! Littlewood–Richardson fill joins its scoped workers with an `expect` that
//! reads any worker panic as a bug, so a cancellation raised inside one would
//! be reported as that bug instead of as itself. The checker is also the
//! embedder's code — under CPython it takes the GIL, which a worker cannot
//! assume it may do. So [`poll`] goes on sequential driver loops, and a
//! parallel section is canceled at the boundary that dispatched it.
//!
//! ## What a checker owes
//!
//! It runs at a point the kernel chose, with the crate's locks released. It
//! must not call back into this library, and it must be cheap enough to run
//! repeatedly — [`poll`] throttles the calls but states no rate. Returning
//! `true` more than once is harmless: the first one already unwound the thread
//! that saw it.
use Cell;
use ;
use ;
use RwLock;
/// The payload of a cancellation panic, and the error [`catch_interrupt`]
/// reports.
///
/// It carries nothing. What a caller wants to know — which signal arrived,
/// what to raise — is the embedder's, and it is the embedder that held that
/// information before it installed the checker.
;
/// Set once at install so [`poll`] can decline in one relaxed load, rather
/// than taking the lock to find the checker absent.
static ARMED: AtomicBool = new;
static CHECKER: = new;
// Polls left before the next call to the checker. Per thread because the
// counter is only a rate limit: two threads sharing one would make each check
// the other's business and add a contended write to every poll.
thread_local!
/// How many polls pass between two calls to the checker.
///
/// The checker is the expensive half — under CPython it reacquires the GIL and
/// runs pending signal handlers — so [`poll`] is placed for a useful bound on
/// *latency* and this divides down the cost of getting one. It is a count and
/// not a duration because a clock read is itself the thing being avoided.
///
/// Public because a test asserting how promptly a cancellation lands has to
/// state the bound in the same unit the throttle uses, and a test holding its
/// own copy of this number would not notice when this one changes.
pub const STRIDE: u32 = 64;
/// Install the checker consulted by [`poll`], replacing any previous one.
///
/// `check` returns `true` to cancel. It is a plain function pointer rather
/// than a closure so that storing it needs no allocation and no type
/// parameter on a `static`; an embedder that needs state reaches it the same
/// way it reached this call.
/// Remove the checker, returning [`poll`] to a no-op.
///
/// Disarms before dropping the pointer, so a poll racing this call either
/// sees the old checker or declines, and never finds `ARMED` set with nothing
/// behind it.
/// Ask the installed checker, at most once per [`STRIDE`] calls, whether the
/// computation should stop — and unwind the thread if it should.
///
/// Call this from loops whose trip count grows with the input, at a boundary
/// crossed often enough to bound how long a cancellation waits. It is not a
/// safepoint in any stronger sense: it does no bookkeeping and leaves nothing
/// for a caller to clean up.
///
/// # Panics
///
/// Panics with [`Interrupted`] when the checker returns `true`. That panic is
/// this module's return path and is meant to be caught by
/// [`catch_interrupt`], not by an intermediate frame.
/// Split from [`poll`] so the common path — decline, or decrement — inlines
/// without the call to the checker behind it.
/// Run `f`, converting a cancellation into `Err(Interrupted)`.
///
/// Any other panic propagates unchanged, which is the whole distinction this
/// module rests on: a violated contract is still a crash, and only the panic
/// this module raised is an ordinary outcome.
///
/// Nested scopes are sound but redundant — the inner one reports first and the
/// outer sees an ordinary `Err`, so a computation is canceled once rather
/// than at every level that happened to wrap it.
/// Whether the panic now unwinding is a cancellation, given its payload.
///
/// A panic hook is handed the payload and cannot catch anything, so it cannot
/// use [`catch_interrupt`] to tell the two apart. An embedder that silences
/// the default hook's report for cancellations — which are expected, and whose
/// report would otherwise reach the user's terminal on every Ctrl-C — asks
/// here and delegates everything else to the hook it replaced.