Skip to main content

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}