Struct DebugSession 

pub struct DebugSession { /* private fields */ }

A debug session attached to a single Lua instance.

Create with DebugSession::new, which also returns a DebugController for the frontend.

Lifecycle

new() → Idle → attach() → Running ⇄ Paused → Terminated

attach is a one-shot operation (per DAP semantics). Calling it on a non-Idle session returns an error. To re-attach, create a new DebugSession.

Implementations

impl DebugSession

pub fn new() -> (Self, DebugController)

Create a new debug session and its associated controller.

The session is in Idle state until attach is called.

Examples found in repository

examples/basic_debug.rs (line 14)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let lua = Lua::new();

    // Create debug session + controller.
    let (session, controller) = DebugSession::new();
    session.attach(&lua)?;

    // Set a breakpoint on line 4.
    let bp_id = controller.set_breakpoint("@example.lua", 4, None)?;
    println!("Breakpoint {bp_id} set at @example.lua:4");

    // Run Lua code on a separate thread.
    // mlua 0.11's LuaError is not Send, so convert to a string error
    // for cross-thread transport.
    let handle = std::thread::spawn(move || -> Result<i64, String> {
        lua.load(
            r#"
local a = 10
local b = 20
local c = 30
local result = a + b + c
return result
"#,
        )
        .set_name("@example.lua")
        .eval::<i64>()
        .map_err(|e| e.to_string())
    });

    // Wait for the breakpoint hit.
    match controller.wait_event()? {
        DebugEvent::Paused { reason, stack } => {
            println!("VM paused: {reason:?}");
            for frame in &stack {
                let line_str = frame
                    .line
                    .map_or_else(|| "?".to_string(), |l| l.to_string());
                println!(
                    "  frame {}: {} ({}:{})",
                    frame.id, frame.name, frame.source, line_str
                );
            }

            // Inspect locals.
            match controller.get_locals(0) {
                Ok(locals) => {
                    println!("Locals:");
                    for var in &locals {
                        println!("  {} = {} ({})", var.name, var.value, var.type_name);
                    }
                }
                Err(e) => println!("Failed to get locals: {e}"),
            }

            // Evaluate an expression.
            match controller.evaluate("a + b", None) {
                Ok(result) => println!("Eval 'a + b' = {result}"),
                Err(e) => println!("Eval failed: {e}"),
            }
        }
        other => println!("Unexpected event: {other:?}"),
    }

    // Resume.
    controller.continue_execution()?;

    // Wait for completion.
    let result = handle.join().unwrap()?;
    println!("Lua returned: {result}");

    Ok(())
}

pub fn attach(&self, lua: &Lua) -> LuaResult<()>

Install the debug hook on the given Lua instance.

After this call, breakpoints and stepping become active.

Errors

Returns an error if the session is not in SessionState::Idle (e.g. already attached or terminated). Per DAP semantics, attach/launch is a one-shot operation per session.

Examples found in repository

examples/basic_debug.rs (line 15)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let lua = Lua::new();

    // Create debug session + controller.
    let (session, controller) = DebugSession::new();
    session.attach(&lua)?;

    // Set a breakpoint on line 4.
    let bp_id = controller.set_breakpoint("@example.lua", 4, None)?;
    println!("Breakpoint {bp_id} set at @example.lua:4");

    // Run Lua code on a separate thread.
    // mlua 0.11's LuaError is not Send, so convert to a string error
    // for cross-thread transport.
    let handle = std::thread::spawn(move || -> Result<i64, String> {
        lua.load(
            r#"
local a = 10
local b = 20
local c = 30
local result = a + b + c
return result
"#,
        )
        .set_name("@example.lua")
        .eval::<i64>()
        .map_err(|e| e.to_string())
    });

    // Wait for the breakpoint hit.
    match controller.wait_event()? {
        DebugEvent::Paused { reason, stack } => {
            println!("VM paused: {reason:?}");
            for frame in &stack {
                let line_str = frame
                    .line
                    .map_or_else(|| "?".to_string(), |l| l.to_string());
                println!(
                    "  frame {}: {} ({}:{})",
                    frame.id, frame.name, frame.source, line_str
                );
            }

            // Inspect locals.
            match controller.get_locals(0) {
                Ok(locals) => {
                    println!("Locals:");
                    for var in &locals {
                        println!("  {} = {} ({})", var.name, var.value, var.type_name);
                    }
                }
                Err(e) => println!("Failed to get locals: {e}"),
            }

            // Evaluate an expression.
            match controller.evaluate("a + b", None) {
                Ok(result) => println!("Eval 'a + b' = {result}"),
                Err(e) => println!("Eval failed: {e}"),
            }
        }
        other => println!("Unexpected event: {other:?}"),
    }

    // Resume.
    controller.continue_execution()?;

    // Wait for completion.
    let result = handle.join().unwrap()?;
    println!("Lua returned: {result}");

    Ok(())
}

pub fn detach(&self, lua: &Lua)

Detach from the Lua instance and terminate the session.

If the VM is paused (blocked in the command loop), this sends a disconnect command to unblock it. A DebugEvent::Terminated event is emitted to notify the frontend.

After detach, this session instance should be dropped. To debug again, create a new DebugSession.

pub fn register_source( &self, name: &str, content: &str, ) -> Result<(), DebugError>

Register source code so the engine can validate breakpoints and display source context.

Errors

Returns DebugError::Internal if the source lock is poisoned (another thread panicked while holding it).

pub fn set_stop_on_entry(&self, stop: bool)

Set whether to pause on the first executable line.

Must be called before attach to guarantee the setting takes effect before the first hook fires.

pub fn completion_notifier(&self) -> CompletionNotifier

Create a CompletionNotifier for signaling execution completion.

Move the returned handle into the thread that runs Lua code. Call CompletionNotifier::notify when execution finishes.

Example

let notifier = session.completion_notifier();
std::thread::spawn(move || {
    let result = lua.load("...").exec();
    notifier.notify(result.err().map(|e| e.to_string()));
});