mlua_isle/hook.rs
1//! Cancellation tokens and the "current token" of a Lua thread.
2//!
3//! A [`CancelToken`] is a shared `AtomicBool` that can be checked from
4//! both Rust code and a Lua debug hook. When the token of the request
5//! (or task) currently executing is cancelled, the cancel hook (see
6//! [Hooks](crate::runtime#hooks)) raises `mlua::Error::external(Cancelled)`
7//! (see [`Cancelled`](crate::Cancelled)), which
8//! [`IsleError::from(mlua::Error)`](crate::IsleError) recognises by
9//! downcast.
10
11use std::cell::RefCell;
12use std::sync::atomic::{AtomicBool, Ordering};
13use std::sync::{Arc, Mutex, Weak};
14
15/// Cancellation signal shared between caller and Lua thread.
16///
17/// Clone is cheap (Arc).
18///
19/// Two cancellation pathways are wired:
20///
21/// 1. A Lua debug hook checks [`is_cancelled`](Self::is_cancelled) every
22/// `N` Lua instructions. This interrupts pure-Lua CPU-bound loops
23/// (`while true do end` etc), including loops inside coroutines
24/// that the Lua code itself creates.
25///
26/// 2. When the feature `tokio` is enabled, [`cancelled`](Self::cancelled)
27/// provides an async signal that fires as soon as [`cancel`](Self::cancel)
28/// is called. Coroutine executors use it to stop a Lua coroutine
29/// even when it is suspended inside a Rust `.await` (e.g. a
30/// `create_async_function` awaiting a tokio child process), a state
31/// in which the debug hook cannot fire because no Lua instructions
32/// execute.
33///
34/// # Hierarchy
35///
36/// [`child_token`](Self::child_token) derives a token that is cancelled
37/// whenever its parent is. A parent holds its children weakly and a
38/// child holds its parent strongly: a finished child disappears from
39/// its parent without an explicit unregister, and a live grandchild
40/// keeps the chain between it and the root alive.
41#[derive(Clone)]
42pub struct CancelToken {
43 inner: Arc<Inner>,
44}
45
46struct Inner {
47 flag: AtomicBool,
48 #[cfg(feature = "tokio")]
49 notify: tokio::sync::Notify,
50 // Kept only to hold the chain to the root alive; never read.
51 _parent: Option<Arc<Inner>>,
52 children: Mutex<Children>,
53}
54
55#[derive(Default)]
56struct Children {
57 list: Vec<Weak<Inner>>,
58 /// `list.len()` at which dead entries are swept next.
59 sweep_at: usize,
60}
61
62impl Inner {
63 fn new(parent: Option<Arc<Inner>>) -> Self {
64 Self {
65 flag: AtomicBool::new(false),
66 #[cfg(feature = "tokio")]
67 notify: tokio::sync::Notify::new(),
68 _parent: parent,
69 children: Mutex::new(Children::default()),
70 }
71 }
72
73 fn cancel(&self) {
74 if self.flag.swap(true, Ordering::AcqRel) {
75 return;
76 }
77 #[cfg(feature = "tokio")]
78 self.notify.notify_waiters();
79 let children = std::mem::take(&mut lock(&self.children).list);
80 for child in children.iter().filter_map(Weak::upgrade) {
81 child.cancel();
82 }
83 }
84}
85
86fn lock(m: &Mutex<Children>) -> std::sync::MutexGuard<'_, Children> {
87 // A panic while holding this lock cannot leave `Children` in an
88 // inconsistent state, so a poisoned lock is still usable.
89 m.lock().unwrap_or_else(|e| e.into_inner())
90}
91
92impl CancelToken {
93 /// Create a new token (not cancelled).
94 pub fn new() -> Self {
95 Self {
96 inner: Arc::new(Inner::new(None)),
97 }
98 }
99
100 /// Derive a child token.
101 ///
102 /// The child is cancelled when this token is cancelled (at once if
103 /// it already is). Cancelling the child does not affect this
104 /// token.
105 pub fn child_token(&self) -> CancelToken {
106 let child = Arc::new(Inner::new(Some(self.inner.clone())));
107 let mut children = lock(&self.inner.children);
108 // Checked under the lock: `Inner::cancel` sets the flag before
109 // taking the lock, so either it sees this child or we see the flag.
110 if self.is_cancelled() {
111 drop(children);
112 child.cancel();
113 } else {
114 if children.list.len() >= children.sweep_at {
115 children.list.retain(|w| w.strong_count() > 0);
116 children.sweep_at = (children.list.len() * 2).max(16);
117 }
118 children.list.push(Arc::downgrade(&child));
119 }
120 CancelToken { inner: child }
121 }
122
123 /// Signal cancellation.
124 ///
125 /// Sets the atomic flag (observed by the Lua debug hook), notifies
126 /// all waiters of the async [`cancelled`](Self::cancelled) signal
127 /// when the `tokio` feature is enabled, and cancels every live
128 /// child token.
129 pub fn cancel(&self) {
130 self.inner.cancel();
131 }
132
133 /// Check whether cancellation has been requested.
134 pub fn is_cancelled(&self) -> bool {
135 self.inner.flag.load(Ordering::Acquire)
136 }
137
138 /// Await cancellation (async).
139 ///
140 /// Returns immediately if already cancelled; otherwise resolves
141 /// when [`cancel`](Self::cancel) is called on this token or one of
142 /// its ancestors.
143 ///
144 /// Race-free: the returned future is registered with the
145 /// underlying [`tokio::sync::Notify`] via
146 /// [`Notified::enable`](tokio::sync::futures::Notified::enable)
147 /// before the flag is re-checked, so a `cancel()` call that
148 /// happens between `cancelled()` being constructed and awaited
149 /// is not lost.
150 #[cfg(feature = "tokio")]
151 pub async fn cancelled(&self) {
152 if self.is_cancelled() {
153 return;
154 }
155 let notified = self.inner.notify.notified();
156 tokio::pin!(notified);
157 notified.as_mut().enable();
158 // Re-check after enabling: a cancel() that happened between
159 // the initial is_cancelled() check and enable() would have
160 // called notify_waiters() without us being registered, so
161 // this second read catches it.
162 if self.is_cancelled() {
163 return;
164 }
165 notified.await;
166 }
167
168 #[cfg(test)]
169 fn live_children(&self) -> usize {
170 lock(&self.inner.children)
171 .list
172 .iter()
173 .filter(|w| w.strong_count() > 0)
174 .count()
175 }
176
177 #[cfg(test)]
178 fn stored_children(&self) -> usize {
179 lock(&self.inner.children).list.len()
180 }
181}
182
183impl Default for CancelToken {
184 fn default() -> Self {
185 Self::new()
186 }
187}
188
189impl std::fmt::Debug for CancelToken {
190 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
191 f.debug_struct("CancelToken")
192 .field("cancelled", &self.is_cancelled())
193 .finish()
194 }
195}
196
197thread_local! {
198 /// Token of the request (or task) currently executing on this Lua
199 /// thread. The cancel hook reads it.
200 static CURRENT: RefCell<Option<CancelToken>> = const { RefCell::new(None) };
201}
202
203/// Token of the request or task currently executing on this thread.
204///
205/// Inside a host function called from Lua code that an isle runs, this
206/// is the token of that request (for coroutine requests and tasks, the
207/// one being polled). Use it to derive a [`child_token`](CancelToken::child_token)
208/// for work the host function starts, so that cancelling the request
209/// reaches that work too. Returns `None` outside such a context.
210///
211/// Work started this way (a `spawn_local` of its own) is cancelled with
212/// the request, but the request neither waits for it nor drops it. To
213/// have the request wait for the work (and drop it when the grace ends),
214/// spawn it through the request's scope with
215/// `runtime::current_scope()` and `ScopeHandle::spawn_local` (`tokio`
216/// feature), or do it inside the future of a
217/// [`create_async_function`](mlua::Lua::create_async_function), so the
218/// coroutine awaits it.
219pub fn current_token() -> Option<CancelToken> {
220 CURRENT.with(|c| c.borrow().clone())
221}
222
223/// Whether the current token is cancelled.
224pub(crate) fn current_is_cancelled() -> bool {
225 CURRENT.with(|c| c.borrow().as_ref().is_some_and(CancelToken::is_cancelled))
226}
227
228/// RAII guard that makes `token` the current token of this thread.
229///
230/// The previous token is restored on drop, so guards nest.
231pub(crate) struct EnterGuard {
232 prev: Option<CancelToken>,
233}
234
235impl EnterGuard {
236 pub(crate) fn new(token: &CancelToken) -> Self {
237 let prev = CURRENT.with(|c| c.replace(Some(token.clone())));
238 Self { prev }
239 }
240}
241
242impl Drop for EnterGuard {
243 fn drop(&mut self) {
244 let prev = self.prev.take();
245 CURRENT.with(|c| *c.borrow_mut() = prev);
246 }
247}
248
249#[cfg(test)]
250mod tests {
251 use super::*;
252
253 #[test]
254 fn token_default_not_cancelled() {
255 let token = CancelToken::new();
256 assert!(!token.is_cancelled());
257 }
258
259 #[test]
260 fn token_cancel_sets_flag() {
261 let token = CancelToken::new();
262 let clone = token.clone();
263 token.cancel();
264 assert!(clone.is_cancelled());
265 }
266
267 #[test]
268 fn cancel_reaches_descendants_not_ancestors() {
269 let root = CancelToken::new();
270 let child = root.child_token();
271 let grandchild = child.child_token();
272 let sibling = root.child_token();
273
274 child.cancel();
275 assert!(child.is_cancelled());
276 assert!(grandchild.is_cancelled());
277 assert!(!root.is_cancelled());
278 assert!(!sibling.is_cancelled());
279
280 root.cancel();
281 assert!(sibling.is_cancelled());
282 }
283
284 #[test]
285 fn child_of_cancelled_token_starts_cancelled() {
286 let root = CancelToken::new();
287 root.cancel();
288 assert!(root.child_token().is_cancelled());
289 }
290
291 #[test]
292 fn grandchild_stays_reachable_after_middle_handle_is_dropped() {
293 let root = CancelToken::new();
294 let grandchild = root.child_token().child_token();
295 root.cancel();
296 assert!(grandchild.is_cancelled());
297 }
298
299 #[test]
300 fn dropped_children_are_swept() {
301 let root = CancelToken::new();
302 let keep = root.child_token();
303 for _ in 0..10_000 {
304 let _ = root.child_token();
305 }
306 assert_eq!(root.live_children(), 1);
307 assert!(
308 root.stored_children() <= 32,
309 "dead children were not swept: {}",
310 root.stored_children()
311 );
312 root.cancel();
313 assert!(keep.is_cancelled());
314 }
315
316 #[test]
317 fn current_token_follows_enter_guards() {
318 assert!(current_token().is_none());
319 let outer = CancelToken::new();
320 let inner = CancelToken::new();
321 {
322 let _o = EnterGuard::new(&outer);
323 {
324 let _i = EnterGuard::new(&inner);
325 inner.cancel();
326 assert!(current_is_cancelled());
327 }
328 assert!(!current_is_cancelled());
329 }
330 assert!(current_token().is_none());
331 }
332}