Implement debugBreak

Signed-off-by: Maksym Pavlenko <pavlenko.maksym@gmail.com>

Author: mxpv

CLAUDE.md

@@ -126,6 +126,20 @@ fn transform(upv: Upvalues(struct { f32, f32 }), x: f32) f32 {
 try table.setClosure("transform", .{ 2.0, 10.0 }, transform);
 ```
 
+## Luau Submodule
+
+This repository includes the full Luau source code as a Git submodule located at `/Users/mpavlenko/Github/luaz/luau`. When investigating Luau implementation details, behavior, or test patterns, use this submodule instead of searching external repositories. The submodule contains:
+
+- VM source code in `luau/VM/src/`
+- Test files in `luau/tests/` (C++ unit tests) and `luau/tests/conformance/` (Luau test scripts)
+- Debug API implementation files like `ldebug.cpp`, `ldo.cpp`, and the main header `lua.h`
+- Conformance tests that demonstrate proper usage patterns for debug functionality
+
+Key test files for understanding debug features:
+- `luau/tests/Conformance.test.cpp` - Contains C++ test code showing how to use `lua_break`, `debuginterrupt`, and breakpoint functionality
+- `luau/tests/conformance/interrupt.luau` - Luau script for testing interrupt functionality
+- `luau/tests/conformance/debugger.luau` - Luau script demonstrating breakpoint usage
+
 ## Development Patterns
 
 ### Versioning and Compatibility
@@ -147,13 +161,20 @@ corresponding unit tests. Tests use `&std.testing.allocator` for memory leak det
 
 Keep unit tests minimal and focused. Tests must demonstrate that functionality works.
 Write clear, concise tests that verify the feature without unnecessary complexity.
+Keep unit tests short and understandable.
 
 Important testing guidelines:
 - `tests.zig` should include unit tests that test only public APIs
 - Avoid using functions from `stack.zig` and `State.zig` in `tests.zig`
+- Never use `stack.*` functions when testing public APIs - use only the high-level API methods
 - Focus on testing the high-level API provided by `lua.zig`
 - Don't create excessive and too verbose unit tests
 - Each test must be minimal and aim to test a specific function
+- Keep tests short, focused, and easy to understand
+- Write meaningful tests that actually test the APIs and their intended behavior
+- Tests must verify that specific API methods work correctly, not just that code runs without crashing
+- Use specific assertions that validate expected outcomes rather than always-true conditions
+- Each test should exercise actual API functionality and verify the correct behavior of the methods being tested
 
 ### Documentation
 Keep documentation for public interfaces current but reasonably sized. The codebase uses Zig's built-in doc comments

src/State.zig

@@ -761,8 +761,10 @@ pub inline fn yield(self: Self, nresults: u32) Status {
 }
 
 /// Break execution
-pub inline fn break_(self: Self) Status {
-    return @enumFromInt(c.lua_break(self.lua));
+pub inline fn break_(self: Self) void {
+    _ = c.lua_break(self.lua);
+    // lua_break always returns -1, which is not meaningful
+    // The function sets L->status = LUA_BREAK internally
 }
 
 /// Resume coroutine

src/debug.zig

@@ -1,3 +1,89 @@
+//! Debug functionality for Luau scripts.
+//!
+//! This module provides debugging support for Luau scripts, including breakpoints,
+//! single-stepping, and execution interruption. The debug system uses a callback-based
+//! approach where the VM notifies your application when debug events occur.
+//!
+//! ## Basic Usage
+//!
+//! 1. Set up debug callbacks using `lua.setCallbacks()`:
+//! ```zig
+//! const DebugCallbacks = struct {
+//!     pub fn debugbreak(self: *@This(), lua: *Lua, ar: Debug) void {
+//!         std.log.info("Hit breakpoint at line {}", .{ar.current_line});
+//!         // Call debugBreak() to actually interrupt execution
+//!         lua.debugBreak();
+//!     }
+//! };
+//!
+//! var callbacks = DebugCallbacks{};
+//! lua.setCallbacks(&callbacks);
+//! ```
+//!
+//! 2. Set breakpoints on functions using `function.setBreakpoint(line)`:
+//! ```zig
+//! // Lua code to debug
+//! const code =
+//!     \\function myFunction()
+//!     \\    local x = 10
+//!     \\    return x + 5  -- This is line 3
+//!     \\end
+//! ;
+//!
+//! _ = try lua.eval(code, .{}, void);
+//! const func = try lua.globals().get("myFunction", Function);
+//! defer func.deinit();
+//!
+//! // Set breakpoint on line 3 of the function
+//! const actual_line = try func.setBreakpoint(3, true);
+//! ```
+//!
+//! 3. Handle interrupted execution:
+//! ```zig
+//! const result = func.call(.{}, i32) catch |err| switch (err) {
+//!     error.Break => {
+//!         // Execution was interrupted at breakpoint
+//!         // Can examine state, variables, etc.
+//!
+//!         // Resume execution by calling the function again
+//!         return func.call(.{}, i32);
+//!     },
+//!     else => return err,
+//! };
+//! ```
+//!
+//! ## Debug Flow
+//!
+//! The debugging process follows this flow:
+//! 1. Breakpoint hit → VM calls your `debugbreak` callback
+//! 2. In callback → Call `lua.debugBreak()` to interrupt execution
+//! 3. VM interrupts → Sets internal status to LUA_BREAK
+//! 4. Function returns → `error.Break` to your application code
+//! 5. Resume execution → Call the function again to continue from where it left off
+//!
+//! ## Key Concepts
+//!
+//! - Breakpoints are notifications: Setting breakpoints with `function.setBreakpoint()` only triggers
+//!   the callback - it doesn't automatically stop execution.
+//! - debugBreak() stops execution: You must call `lua.debugBreak()` within your
+//!   callback to actually interrupt and return control to your application.
+//! - Resumption: After `error.Break`, call the same function again to resume execution.
+//! - Debug info limitations: Only `current_line` and `userdata` fields are populated
+//!   in debug callbacks. Other fields contain garbage values.
+//!
+//! ## Advanced Features
+//!
+//! - Single stepping: Use `lua.setSingleStep(true)` and the `debugstep` callback
+//! - Thread interruption: Use `debuginterrupt` callback for coroutine debugging
+//! - Function breakpoints: Use `function.setBreakpoint(line)` to set breakpoints on specific functions
+//! - Conditional breakpoints: Only call `debugBreak()` when certain conditions are met
+//!
+//! ## Debug Information
+//!
+//! The `Debug` struct contains information about the current execution context,
+//! but note that most fields are only populated during `lua_getinfo()` calls,
+//! not during debug hook callbacks.
+
 const std = @import("std");
 const State = @import("State.zig");
 
@@ -21,6 +107,8 @@ pub const Debug = struct {
     param_count: u8,
     /// Whether function accepts variable arguments
     is_vararg: bool,
+    /// Optional user data (for debuginterrupt, contains the interrupted thread state)
+    userdata: ?*anyopaque,
 
     /// Creates a Debug struct from a C lua_Debug pointer
     ///
@@ -37,15 +125,27 @@ pub const Debug = struct {
     /// function on the stack which is more complex.
     pub fn fromC(c_debug: *State.Debug) Debug {
         return Debug{
-            .name = if (c_debug.name) |n| std.mem.span(n) else null,
-            .what = if (c_debug.what) |w| std.mem.span(w) else "unknown",
-            .source = if (c_debug.source) |s| std.mem.span(s) else "unknown",
-            .short_src = if (c_debug.short_src) |s| std.mem.span(s) else "unknown",
+            .name = null,
+            .what = "",
+            .source = "",
+            .short_src = "",
             .line_defined = c_debug.linedefined,
             .current_line = c_debug.currentline,
             .upvalue_count = c_debug.nupvals,
             .param_count = c_debug.nparams,
             .is_vararg = c_debug.isvararg != 0,
+            .userdata = c_debug.userdata,
         };
     }
+
+    /// Gets the interrupted thread from debuginterrupt callback userdata.
+    /// Returns null if userdata is null or not a valid thread state.
+    /// Only valid when called from debuginterrupt callback.
+    pub fn getInterruptedThread(self: Debug) ?State {
+        if (self.userdata) |data| {
+            const lua_state: State.LuaState = @ptrCast(@alignCast(data));
+            return State{ .lua = lua_state };
+        }
+        return null;
+    }
 };

src/lua.zig

@@ -73,6 +73,8 @@ pub const Lua = struct {
         Runtime,
         /// Breakpoint could not be set at the specified line.
         InvalidBreakpoint,
+        /// Debug break occurred during execution.
+        Break,
     };
 
     /// Assert handler function type for Luau VM assertions.
@@ -213,10 +215,13 @@ pub const Lua = struct {
     /// - `panic(state: *State, errcode: i32) void` - Called on unprotected errors (if longjmp is used)
     /// - `userthread(parent: ?*State, thread: *State) void` - Called when thread is created/destroyed
     /// - `useratom(s: []const u8) i16` - Called when string is created; returns atom ID
-    /// - `debugbreak(state: *State, ar: Debug) void` - Called on BREAK instruction
-    /// - `debugstep(state: *State, ar: Debug) void` - Called after each instruction in single step
-    /// - `debuginterrupt(state: *State, ar: Debug) void` - Called on thread execution interrupt
-    /// - `debugprotectederror(state: *State) void` - Called when protected call results in error
+    /// - `debugbreak(lua: *Lua, ar: Debug) void` - Called when breakpoint is hit. Note that breakpoints
+    ///   set with `breakpoint(line)` in Lua code only trigger this callback - they don't automatically
+    ///   interrupt execution. Call `lua.debugBreak()` within this callback to actually interrupt
+    ///   execution and return `error.Break` to the caller.
+    /// - `debugstep(lua: *Lua, ar: Debug) void` - Called after each instruction in single step
+    /// - `debuginterrupt(lua: *Lua, ar: Debug) void` - Called on thread execution interrupt
+    /// - `debugprotectederror(lua: *Lua) void` - Called when protected call results in error
     /// - `onallocate(state: *State, osize: usize, nsize: usize) void` - Called when a memory operation occurs
     ///   (allocation when osize=0, deallocation when nsize=0, reallocation otherwise).
     ///   Note: This callback is only triggered for Luau's internal allocations, not for all memory operations
@@ -348,15 +353,15 @@ pub const Lua = struct {
         if (@hasDecl(CallbackType, "debugbreak")) {
             cb.debugbreak = struct {
                 fn wrapper(L: ?State.LuaState, ar: ?*State.Debug) callconv(.C) void {
-                    var state = State{ .lua = L.? };
+                    var lua = Lua.fromState(L.?);
                     const debug_info = debug.Debug.fromC(ar.?);
 
                     if (comptime is_instance) {
-                        const callbacks_struct = state.callbacks();
+                        const callbacks_struct = lua.state.callbacks();
                         const instance: *CallbackType = @ptrCast(@alignCast(callbacks_struct.userdata.?));
-                        instance.debugbreak(&state, debug_info);
+                        instance.debugbreak(&lua, debug_info);
                     } else {
-                        CallbackType.debugbreak(&state, debug_info);
+                        CallbackType.debugbreak(&lua, debug_info);
                     }
                 }
             }.wrapper;
@@ -365,15 +370,15 @@ pub const Lua = struct {
         if (@hasDecl(CallbackType, "debugstep")) {
             cb.debugstep = struct {
                 fn wrapper(L: ?State.LuaState, ar: ?*State.Debug) callconv(.C) void {
-                    var state = State{ .lua = L.? };
+                    var lua = Lua.fromState(L.?);
                     const debug_info = debug.Debug.fromC(ar.?);
 
                     if (comptime is_instance) {
-                        const callbacks_struct = state.callbacks();
+                        const callbacks_struct = lua.state.callbacks();
                         const instance: *CallbackType = @ptrCast(@alignCast(callbacks_struct.userdata.?));
-                        instance.debugstep(&state, debug_info);
+                        instance.debugstep(&lua, debug_info);
                     } else {
-                        CallbackType.debugstep(&state, debug_info);
+                        CallbackType.debugstep(&lua, debug_info);
                     }
                 }
             }.wrapper;
@@ -382,15 +387,15 @@ pub const Lua = struct {
         if (@hasDecl(CallbackType, "debuginterrupt")) {
             cb.debuginterrupt = struct {
                 fn wrapper(L: ?State.LuaState, ar: ?*State.Debug) callconv(.C) void {
-                    var state = State{ .lua = L.? };
+                    var lua = Lua.fromState(L.?);
                     const debug_info = debug.Debug.fromC(ar.?);
 
                     if (comptime is_instance) {
-                        const callbacks_struct = state.callbacks();
+                        const callbacks_struct = lua.state.callbacks();
                         const instance: *CallbackType = @ptrCast(@alignCast(callbacks_struct.userdata.?));
-                        instance.debuginterrupt(&state, debug_info);
+                        instance.debuginterrupt(&lua, debug_info);
                     } else {
-                        CallbackType.debuginterrupt(&state, debug_info);
+                        CallbackType.debuginterrupt(&lua, debug_info);
                     }
                 }
             }.wrapper;
@@ -399,14 +404,14 @@ pub const Lua = struct {
         if (@hasDecl(CallbackType, "debugprotectederror")) {
             cb.debugprotectederror = struct {
                 fn wrapper(L: ?State.LuaState) callconv(.C) void {
-                    var state = State{ .lua = L.? };
+                    var lua = Lua.fromState(L.?);
 
                     if (comptime is_instance) {
-                        const callbacks_struct = state.callbacks();
+                        const callbacks_struct = lua.state.callbacks();
                         const instance: *CallbackType = @ptrCast(@alignCast(callbacks_struct.userdata.?));
-                        instance.debugprotectederror(&state);
+                        instance.debugprotectederror(&lua);
                     } else {
-                        CallbackType.debugprotectederror(&state);
+                        CallbackType.debugprotectederror(&lua);
                     }
                 }
             }.wrapper;
@@ -415,8 +420,8 @@ pub const Lua = struct {
         if (@hasDecl(CallbackType, "onallocate")) {
             cb.onallocate = struct {
                 fn wrapper(L: ?State.LuaState, osize: usize, nsize: usize) callconv(.C) void {
-                    if (L) |lua| {
-                        var state = State{ .lua = lua };
+                    if (L) |lua_state| {
+                        var state = State{ .lua = lua_state };
 
                         if (comptime is_instance) {
                             const callbacks_struct = state.callbacks();
@@ -471,6 +476,50 @@ pub const Lua = struct {
         self.state.singleStep(enabled);
     }
 
+    /// Interrupt thread execution during debug callbacks.
+    ///
+    /// This method should be called from within debug callbacks (debugbreak, debugstep, debuginterrupt)
+    /// to interrupt the current execution and return control to the caller. When called, it sets the
+    /// VM's status to LUA_BREAK, causing the current function to return with `error.Break`.
+    ///
+    /// Note: Breakpoints set with `breakpoint(line)` in Lua code only trigger debug callbacks - they
+    /// don't automatically interrupt execution. You must call `debugBreak()` within your callback
+    /// to actually interrupt and return control to your application.
+    ///
+    /// Flow:
+    /// 1. Breakpoint hits → VM calls your debugbreak callback
+    /// 2. In callback → call `debugBreak()` to interrupt execution
+    /// 3. VM sets status → L.status = LUA_BREAK
+    /// 4. Function returns → `error.Break` to caller
+    /// 5. Can resume → call function again to continue from where it left off
+    ///
+    /// Example:
+    /// ```zig
+    /// const DebugCallbacks = struct {
+    ///     pub fn debugbreak(self: *@This(), lua: *Lua, ar: Debug) void {
+    ///         std.log.info("Hit breakpoint at line {}", .{ar.current_line});
+    ///         // This actually interrupts execution and returns error.Break
+    ///         lua.debugBreak();
+    ///     }
+    /// };
+    ///
+    /// var callbacks = DebugCallbacks{};
+    /// lua.setCallbacks(&callbacks);
+    ///
+    /// // When breakpoint hits, function returns error.Break instead of continuing
+    /// const result = func.call(.{}, i32) catch |err| switch (err) {
+    ///     error.Break => {
+    ///         // Execution was interrupted, can examine state or resume later
+    ///         return func.call(.{}, i32); // Resume execution
+    ///     },
+    ///     else => return err,
+    /// };
+    /// ```
+    ///
+    pub fn debugBreak(self: Self) void {
+        self.state.break_();
+    }
+
     /// A reference to a Lua value.
     ///
     /// Holds a reference ID that can be used to retrieve the value later.
@@ -833,6 +882,7 @@ pub const Lua = struct {
             const result = self.ref.lua.call(args, R, false);
             return switch (result.status) {
                 .ok, .yield => result.result.?,
+                .break_debug => error.Break,
                 .errmem => error.OutOfMemory,
                 else => error.Runtime,
             };
@@ -1662,6 +1712,7 @@ pub const Lua = struct {
 
             return switch (result.status) {
                 .ok, .yield => result.result.?,
+                .break_debug => error.Break,
                 .errmem => error.OutOfMemory,
                 else => error.Runtime,
             };