Struct DebugController 

pub struct DebugController { /* private fields */ }

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

Thread-safe: Clone + Send + Sync.

Implementations

impl DebugController

pub fn state(&self) -> SessionState

Current session state (non-blocking, coarse-grained).

Returns whether the VM is Idle, Running, Paused, or Terminated. PauseReason is not preserved in the atomic representation — use wait_event to obtain the precise reason from DebugEvent::Paused.

pub fn wait_event(&self) -> Result<DebugEvent, DebugError>

Block until the next event arrives from the engine.

This is the authoritative source for session events. In particular, DebugEvent::Paused carries the precise PauseReason that state() does not preserve.

Examples found in repository

examples/basic_debug.rs (line 40)

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 try_event(&self) -> Result<Option<DebugEvent>, DebugError>

Try to receive an event without blocking.

pub fn wait_event_timeout( &self, timeout: Duration, ) -> Result<Option<DebugEvent>, DebugError>

Block until the next event arrives, with a timeout.

Returns Ok(None) if the timeout elapses without an event.

pub fn set_breakpoint( &self, source: &str, line: usize, condition: Option<&str>, ) -> Result<BreakpointId, DebugError>

Set a breakpoint. Returns the assigned ID.

Works in any session state (Idle, Running, Paused, Terminated) — the breakpoint registry is shared via Arc<Mutex<…>> and accessed directly, not through the command channel.

Examples found in repository

examples/basic_debug.rs (line 18)

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 remove_breakpoint(&self, id: BreakpointId) -> Result<bool, DebugError>

Remove a breakpoint by ID.

pub fn list_breakpoints(&self) -> Result<Vec<Breakpoint>, DebugError>

List all breakpoints.

pub fn continue_execution(&self) -> Result<(), DebugError>

Resume execution.

Examples found in repository

examples/basic_debug.rs (line 74)

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 step_into(&self) -> Result<(), DebugError>

Step into the next line (descend into calls).

pub fn step_over(&self) -> Result<(), DebugError>

Step to the next line at the same or shallower call depth.

pub fn step_out(&self) -> Result<(), DebugError>

Step out of the current function.

pub fn pause(&self) -> Result<(), DebugError>

Request the VM to pause at the next opportunity.

Sets an atomic flag that is checked on every Lua line event. Effective in any state — if the VM is Running, it will pause at the next executed line.

pub fn get_stack_trace(&self) -> Result<Vec<StackFrame>, DebugError>

Get the current call stack.

pub fn get_locals(&self, frame_id: usize) -> Result<Vec<Variable>, DebugError>

Get local variables at a stack frame.

Examples found in repository

examples/basic_debug.rs (line 54)

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 get_upvalues(&self, frame_id: usize) -> Result<Vec<Variable>, DebugError>

Get upvalues at a stack frame.

pub fn evaluate( &self, expression: &str, frame_id: Option<usize>, ) -> Result<String, DebugError>

Evaluate a Lua expression while paused.

When frame_id is Some, the expression is evaluated in the scope of that stack frame — locals, upvalues, and globals are all accessible. When None, evaluation runs in the global scope only.

Examples found in repository

examples/basic_debug.rs (line 65)

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 disconnect(&self) -> Result<(), DebugError>

Disconnect from the session.

Trait Implementations

impl Clone for DebugController

fn clone(&self) -> DebugController

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.