mlua_probe_core/
lib.rs

1//! Core debug engine for mlua.
2//!
3//! Provides breakpoints, stepping, variable inspection, and expression
4//! evaluation for Lua code running inside an mlua `Lua` instance.
5//!
6//! # Architecture
7//!
8//! The engine uses a **VM-thread blocking** model:
9//!
10//! - A Lua debug hook pauses the VM thread when a breakpoint or step
11//!   condition is met.
12//! - While paused, the hook dispatches inspection commands (locals,
13//!   upvalues, evaluate) **on the VM thread** — required because
14//!   `lua_getlocal` and friends are not thread-safe.
15//! - A resume command (continue / step) unblocks the hook and lets
16//!   Lua execution proceed.
17//!
18//! # Usage
19//!
20//! ```rust,no_run
21//! use mlua::prelude::*;
22//! use mlua_probe_core::{DebugSession, DebugEvent};
23//!
24//! let lua = Lua::new();
25//! let (session, controller) = DebugSession::new();
26//! session.attach(&lua).unwrap();
27//!
28//! controller.set_breakpoint("@main.lua", 3, None).unwrap();
29//!
30//! // Run Lua on a separate thread so the current thread can
31//! // interact with the controller.
32//! let handle = std::thread::spawn(move || {
33//!     lua.load(r#"
34//!         local x = 1
35//!         local y = 2
36//!         local z = x + y
37//!         return z
38//!     "#)
39//!     .set_name("@main.lua")
40//!     .eval::<i64>()
41//! });
42//!
43//! // Wait for the VM to pause.
44//! let event = controller.wait_event().unwrap();
45//! // Inspect, step, continue …
46//! controller.continue_execution().unwrap();
47//!
48//! let result = handle.join().unwrap().unwrap();
49//! assert_eq!(result, 3);
50//! ```
51
52mod debug;
53
54pub use debug::breakpoint::Breakpoint;
55pub use debug::controller::DebugController;
56pub use debug::engine::{CompletionNotifier, DebugSession};
57pub use debug::error::DebugError;
58pub use debug::types::{
59    BreakpointId, DebugEvent, FrameKind, OutputCategory, PauseReason, SessionState, StackFrame,
60    StepMode, Variable, VariableRef,
61};
mlua_probe_core/lib.rs

mlua_probe_core/
lib.rs
