Skip to main content

mlua_isle/
hooks.rs

1//! The Lua debug hook of an isle, shared between cancellation and user
2//! callbacks.
3//!
4//! Lua has one hook slot per thread, and mlua's hook setters replace
5//! whatever was there.  An isle therefore owns the VM's hook: it
6//! installs a single **global** hook ([`mlua::Lua::set_global_hook`])
7//! whose callback, in order,
8//!
9//! 1. raises the cancellation error when the token of the request or
10//!    task currently executing is cancelled,
11//! 2. calls the callbacks registered with [`add_hook`], each at its own
12//!    [`HookTriggers`],
13//! 3. yields the running task every N instruction checks when
14//!    preemption is enabled (see [`CancelConfig::preempt_every`]).
15//!
16//! A global hook is used because a per-thread hook does not reach
17//! coroutines created from Lua (`coroutine.create` / `coroutine.wrap`):
18//! Lua copies the C hook into the new thread, but mlua finds no
19//! callback registered for that thread and removes the hook the first
20//! time it fires.  The global hook's callback is shared by every thread
21//! of the VM.
22//!
23//! # Do not set hooks directly
24//!
25//! Calling [`mlua::Lua::set_hook`], [`mlua::Lua::set_global_hook`] or
26//! [`mlua::Thread::set_hook`] on an isle's VM replaces this hook, and
27//! cancellation stops working.  Register callbacks with [`add_hook`]
28//! instead.  An isle re-installs its hook when it notices that
29//! `set_hook` replaced it (checked at the start of every request), but
30//! a replacement through `set_global_hook` cannot be detected.
31
32use crate::error::IsleError;
33use crate::hook::{self, CANCELLED_SENTINEL};
34use mlua::debug::{Debug, DebugEvent};
35use mlua::{HookTriggers, Lua, VmState};
36use std::cell::{Cell, RefCell};
37use std::collections::HashSet;
38use std::rc::Rc;
39use std::time::Duration;
40
41/// Instruction interval of the cancel check.
42pub(crate) const CANCEL_CHECK_INTERVAL: u32 = 1000;
43
44/// Handle of a callback registered with [`add_hook`].
45#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
46pub struct HookId(u64);
47
48type Callback = dyn Fn(&Lua, &Debug) -> mlua::Result<VmState>;
49
50struct Entry {
51    id: HookId,
52    triggers: HookTriggers,
53    callback: Box<Callback>,
54    /// Instructions counted since this entry last ran (count triggers).
55    counted: Cell<u32>,
56}
57
58/// Cancellation settings of a VM.  Set with [`configure`].
59#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
60pub struct CancelConfig {
61    /// How long a cancelled coroutine request or task may keep running
62    /// to finish its cleanup before it is dropped.
63    ///
64    /// On cancel, the coroutine first receives the cancellation as a Lua
65    /// error (from the cancel hook while it runs, or from an async
66    /// function wrapped with [`cancellable`](crate::cancellable) while
67    /// it awaits).  That error unwinds normally, so `__close` handlers
68    /// run and may await.  If the coroutine has not finished when the
69    /// grace period ends, it is dropped: the awaited Rust future is
70    /// released, and pending `__close` handlers run without being able
71    /// to yield (a Lua 5.4 restriction).
72    ///
73    /// Default: zero (drop at once).
74    pub grace: Duration,
75    /// Yield the running coroutine request or task every this many
76    /// cancel checks (a check runs every 1000 instructions), so that
77    /// other tasks on the same thread —
78    /// including one that cancels it — get to run while it is in a CPU
79    /// loop.
80    ///
81    /// Only the coroutine that the isle created for the request or task
82    /// is yielded, never a coroutine the Lua code created itself (that
83    /// yield would reach the Lua code's own `coroutine.resume` as a
84    /// spurious yield).  Code in a non-yieldable context (a metamethod,
85    /// a C function boundary) is not yielded.
86    ///
87    /// Yielding lets other tasks interleave at points the Lua code did
88    /// not mark, so Lua code that updates shared state across such a
89    /// point can observe changes made by another task.
90    ///
91    /// Default: `None` (never preempt).
92    pub preempt_every: Option<u32>,
93}
94
95#[derive(Default)]
96struct Hub {
97    entries: RefCell<Vec<Rc<Entry>>>,
98    next_id: Cell<u64>,
99    config: Cell<CancelConfig>,
100    checks: Cell<u32>,
101    /// Raw hook function of the main thread right after installation.
102    installed: Cell<usize>,
103}
104
105thread_local! {
106    /// Coroutines created by the isle for a coroutine request or task
107    /// (the only ones preemption may yield), by thread pointer.
108    static ROOTS: RefCell<HashSet<usize>> = RefCell::new(HashSet::new());
109}
110
111#[cfg(feature = "tokio")]
112pub(crate) fn mark_root(ptr: usize) {
113    ROOTS.with(|r| r.borrow_mut().insert(ptr));
114}
115
116#[cfg(feature = "tokio")]
117pub(crate) fn unmark_root(ptr: usize) {
118    ROOTS.with(|r| r.borrow_mut().remove(&ptr));
119}
120
121fn hub(lua: &Lua) -> Rc<Hub> {
122    if let Some(h) = lua.app_data_ref::<Rc<Hub>>() {
123        return h.clone();
124    }
125    let h = Rc::new(Hub::default());
126    lua.set_app_data(h.clone());
127    h
128}
129
130/// Install (or re-install) the isle hook on `lua`.
131///
132/// Called by the isles after the init closure; call it yourself when
133/// you run Lua with this crate's cancellation or task support outside
134/// an isle.
135pub fn install(lua: &Lua) -> Result<(), IsleError> {
136    let hub = hub(lua);
137    let mut triggers = HookTriggers::new().every_nth_instruction(CANCEL_CHECK_INTERVAL);
138    for e in hub.entries.borrow().iter() {
139        triggers.on_calls |= e.triggers.on_calls;
140        triggers.on_returns |= e.triggers.on_returns;
141        triggers.every_line |= e.triggers.every_line;
142        if let Some(n) = e.triggers.every_nth_instruction {
143            let cur = triggers.every_nth_instruction.unwrap_or(n);
144            triggers.every_nth_instruction = Some(cur.min(n).max(1));
145        }
146    }
147    let step = triggers.every_nth_instruction.unwrap_or(1);
148    let cancel_every = CANCEL_CHECK_INTERVAL.div_ceil(step).max(1);
149    lua.set_global_hook(triggers, move |lua, debug| {
150        dispatch(lua, debug, step, cancel_every)
151    })
152    .map_err(IsleError::from)?;
153    hub.installed.set(raw_hook(lua));
154    Ok(())
155}
156
157/// Re-install the isle hook if `Lua::set_hook` replaced it.
158pub(crate) fn ensure_installed(lua: &Lua) -> Result<(), IsleError> {
159    let hub = hub(lua);
160    if hub.installed.get() == 0 || raw_hook(lua) != hub.installed.get() {
161        install(lua)?;
162    }
163    Ok(())
164}
165
166fn raw_hook(lua: &Lua) -> usize {
167    let mut out = 0usize;
168    // SAFETY: `lua_gethook` only reads the hook field of the state.
169    let _ = unsafe {
170        lua.exec_raw::<()>((), |state| {
171            out = mlua::ffi::lua_gethook(state).map_or(0, |f| f as usize);
172        })
173    };
174    out
175}
176
177fn dispatch(lua: &Lua, debug: &Debug, step: u32, cancel_every: u32) -> mlua::Result<VmState> {
178    let event = debug.event();
179    let hub = hub(lua);
180    let mut want_yield = false;
181
182    if matches!(event, DebugEvent::Count) {
183        let checks = hub.checks.get().wrapping_add(1);
184        hub.checks.set(checks);
185        if checks.is_multiple_of(cancel_every) {
186            if hook::current_is_cancelled() {
187                return Err(mlua::Error::runtime(CANCELLED_SENTINEL));
188            }
189            if let Some(n) = hub.config.get().preempt_every {
190                if (checks / cancel_every).is_multiple_of(n.max(1)) && is_root(lua) {
191                    want_yield = true;
192                }
193            }
194        }
195    }
196
197    // Snapshot so that a callback may add or remove hooks.
198    let entries: Vec<Rc<Entry>> = hub.entries.borrow().clone();
199    for e in entries {
200        let t = &e.triggers;
201        let fire = match event {
202            DebugEvent::Count => match t.every_nth_instruction {
203                Some(n) => {
204                    let c = e.counted.get() + step;
205                    if c >= n {
206                        e.counted.set(0);
207                        true
208                    } else {
209                        e.counted.set(c);
210                        false
211                    }
212                }
213                None => false,
214            },
215            DebugEvent::Line => t.every_line,
216            DebugEvent::Call | DebugEvent::TailCall => t.on_calls,
217            DebugEvent::Ret => t.on_returns,
218            DebugEvent::Unknown(_) => false,
219        };
220        if fire && matches!((e.callback)(lua, debug)?, VmState::Yield) {
221            want_yield = true;
222        }
223    }
224
225    Ok(if want_yield {
226        VmState::Yield
227    } else {
228        VmState::Continue
229    })
230}
231
232fn is_root(lua: &Lua) -> bool {
233    let ptr = lua.current_thread().to_pointer() as usize;
234    ROOTS.with(|r| r.borrow().contains(&ptr))
235}
236
237/// Register a hook callback on an isle's VM.
238///
239/// The callback runs from the isle's single global hook, after the
240/// cancel check, at `triggers`.  Instruction counts are approximated to
241/// the hook's step (the smallest count among all registrations and the
242/// cancel check).  Returning [`VmState::Yield`] yields the running
243/// coroutine, including a coroutine the Lua code created itself, where
244/// the yield reaches the Lua code's `coroutine.resume`.
245///
246/// Call it in the init closure or from an `exec` closure.  The callback
247/// applies to the main thread and to coroutines created afterwards;
248/// coroutines that already exist keep the instruction count and events
249/// they were created with.
250pub fn add_hook<F>(lua: &Lua, triggers: HookTriggers, callback: F) -> Result<HookId, IsleError>
251where
252    F: Fn(&Lua, &Debug) -> mlua::Result<VmState> + 'static,
253{
254    let hub = hub(lua);
255    let id = HookId(hub.next_id.get());
256    hub.next_id.set(id.0 + 1);
257    hub.entries.borrow_mut().push(Rc::new(Entry {
258        id,
259        triggers,
260        callback: Box::new(callback),
261        counted: Cell::new(0),
262    }));
263    install(lua)?;
264    Ok(id)
265}
266
267/// Remove a callback registered with [`add_hook`].  Returns whether it
268/// was registered.
269pub fn remove_hook(lua: &Lua, id: HookId) -> Result<bool, IsleError> {
270    let hub = hub(lua);
271    let before = hub.entries.borrow().len();
272    hub.entries.borrow_mut().retain(|e| e.id != id);
273    let removed = hub.entries.borrow().len() != before;
274    if removed {
275        install(lua)?;
276    }
277    Ok(removed)
278}
279
280/// Set the cancellation settings of a VM.
281pub fn configure(lua: &Lua, config: CancelConfig) {
282    hub(lua).config.set(config);
283}
284
285/// The cancellation settings of a VM.
286pub fn config(lua: &Lua) -> CancelConfig {
287    hub(lua).config.get()
288}
289
290#[cfg(test)]
291mod tests {
292    use super::*;
293    use crate::hook::{CancelToken, EnterGuard};
294
295    fn cancel_soon(token: &CancelToken) {
296        let t = token.clone();
297        std::thread::spawn(move || {
298            std::thread::sleep(Duration::from_millis(10));
299            t.cancel();
300        });
301    }
302
303    fn assert_cancelled(r: mlua::Result<()>) {
304        let msg = r.unwrap_err().to_string();
305        assert!(msg.contains(CANCELLED_SENTINEL), "got: {msg}");
306    }
307
308    #[test]
309    fn hook_interrupts_lua_loop() {
310        let lua = Lua::new();
311        install(&lua).unwrap();
312        let token = CancelToken::new();
313        let _enter = EnterGuard::new(&token);
314        cancel_soon(&token);
315        assert_cancelled(lua.load("while true do end").exec());
316    }
317
318    #[test]
319    fn hook_interrupts_loop_in_lua_created_coroutine() {
320        let lua = Lua::new();
321        install(&lua).unwrap();
322        let token = CancelToken::new();
323        let _enter = EnterGuard::new(&token);
324        cancel_soon(&token);
325        assert_cancelled(
326            lua.load("coroutine.wrap(function() while true do end end)()")
327                .exec(),
328        );
329    }
330
331    #[test]
332    fn hook_ignores_cancelled_token_that_is_not_current() {
333        let lua = Lua::new();
334        install(&lua).unwrap();
335        let other = CancelToken::new();
336        other.cancel();
337        let _outer = EnterGuard::new(&other);
338        let _inner = EnterGuard::new(&CancelToken::new());
339        let r: i64 = lua
340            .load("local n = 0 for i = 1, 100000 do n = n + 1 end return n")
341            .eval()
342            .unwrap();
343        assert_eq!(r, 100000);
344    }
345
346    #[test]
347    fn user_callbacks_share_the_hook_with_cancellation() {
348        let lua = Lua::new();
349        install(&lua).unwrap();
350        let lines = Rc::new(Cell::new(0u32));
351        let counts = Rc::new(Cell::new(0u32));
352        let (l, c) = (lines.clone(), counts.clone());
353        add_hook(&lua, HookTriggers::EVERY_LINE, move |_, _| {
354            l.set(l.get() + 1);
355            Ok(VmState::Continue)
356        })
357        .unwrap();
358        add_hook(
359            &lua,
360            HookTriggers::new().every_nth_instruction(10_000),
361            move |_, _| {
362                c.set(c.get() + 1);
363                Ok(VmState::Continue)
364            },
365        )
366        .unwrap();
367
368        // Lines inside a Lua-created coroutine reach the user callback.
369        lua.load("local co = coroutine.wrap(function()\n local x = 1\n x = x + 1\n end)\n co()")
370            .exec()
371            .unwrap();
372        assert!(lines.get() >= 4, "line callback ran {} times", lines.get());
373
374        lua.load("local n = 0 for i = 1, 1000000 do n = n + 1 end")
375            .exec()
376            .unwrap();
377        assert!(counts.get() > 0, "count callback never ran");
378
379        // Cancellation still works next to the user callbacks.
380        let token = CancelToken::new();
381        let _enter = EnterGuard::new(&token);
382        cancel_soon(&token);
383        assert_cancelled(lua.load("while true do end").exec());
384    }
385
386    #[test]
387    fn user_callback_error_propagates_and_remove_hook_stops_it() {
388        let lua = Lua::new();
389        install(&lua).unwrap();
390        let id = add_hook(&lua, HookTriggers::EVERY_LINE, |_, _| {
391            Err(mlua::Error::runtime("limit reached"))
392        })
393        .unwrap();
394        let err = lua.load("local x = 1").exec().unwrap_err().to_string();
395        assert!(err.contains("limit reached"), "got: {err}");
396
397        assert!(remove_hook(&lua, id).unwrap());
398        assert!(!remove_hook(&lua, id).unwrap());
399        lua.load("local x = 1").exec().unwrap();
400    }
401
402    #[test]
403    fn ensure_installed_restores_hook_replaced_by_set_hook() {
404        let lua = Lua::new();
405        install(&lua).unwrap();
406        lua.set_hook(HookTriggers::EVERY_LINE, |_, _| Ok(VmState::Continue))
407            .unwrap();
408        ensure_installed(&lua).unwrap();
409
410        let token = CancelToken::new();
411        let _enter = EnterGuard::new(&token);
412        cancel_soon(&token);
413        assert_cancelled(lua.load("while true do end").exec());
414    }
415}