Crate mlua_probe_core 

Core debug engine for mlua.

Provides breakpoints, stepping, variable inspection, and expression evaluation for Lua code running inside an mlua Lua instance.

Architecture

The engine uses a VM-thread blocking model:

• A Lua debug hook pauses the VM thread when a breakpoint or step condition is met.
• While paused, the hook dispatches inspection commands (locals, upvalues, evaluate) on the VM thread — required because lua_getlocal and friends are not thread-safe.
• A resume command (continue / step) unblocks the hook and lets Lua execution proceed.

Usage

use mlua::prelude::*;
use mlua_probe_core::{DebugSession, DebugEvent};

let lua = Lua::new();
let (session, controller) = DebugSession::new();
session.attach(&lua).unwrap();

controller.set_breakpoint("@main.lua", 3, None).unwrap();

// Run Lua on a separate thread so the current thread can
// interact with the controller.
let handle = std::thread::spawn(move || {
    lua.load(r#"
        local x = 1
        local y = 2
        local z = x + y
        return z
    "#)
    .set_name("@main.lua")
    .eval::<i64>()
});

// Wait for the VM to pause.
let event = controller.wait_event().unwrap();
// Inspect, step, continue …
controller.continue_execution().unwrap();

let result = handle.join().unwrap().unwrap();
assert_eq!(result, 3);

Structs

Breakpoint

A single breakpoint definition.

BreakpointId

Unique identifier for a breakpoint.

CompletionNotifier

A handle for notifying the session that Lua execution has completed.

DebugController

Controls a DebugSession from a frontend (MCP server, DAP adapter, Web console, …).

DebugSession

A debug session attached to a single Lua instance.

StackFrame

A single frame in the Lua call stack.

Variable

A single variable (local, upvalue, or global).

VariableRef

Opaque handle used to expand structured values (tables) on demand.

Enums

DebugError

Errors returned by DebugController and DebugSession methods.

DebugEvent

An event emitted by the debug engine.

FrameKind

What produced this stack frame.

OutputCategory

Category for DebugEvent::Output.

PauseReason

Why the VM was paused.

SessionState

State of a debug session.

StepMode

How the stepping engine should behave after a resume.