From bb2033969123d378d58f5a2a026e27a19222154f Mon Sep 17 00:00:00 2001 From: agra Date: Mon, 1 Jun 2026 08:58:57 +0300 Subject: [PATCH] ERR/E3.3: trace formatting (library/modules/trace.sx) + catch-clear timing fix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The trace formatter, unblocked now that 0057 is fixed. - library/modules/trace.sx: to_string() walks the trace buffer (sx_trace_len / frame_at / truncated) and renders "error return trace ..." with one line per frame; print_current() writes it to stderr (libc write(2, ...)). Frame locations are "" until E3.0 resolves PCs; count + ordering + the overflow note are already meaningful. - Catch-clear timing fix (lowerCatch): move the absorption clear from runCatchBody ENTRY to the handler's non-diverging EXIT (both the pure and value-carrying paths). This reconciles the two PLAN-ERR statements that conflicted — §clear-points "buffer cleared before the catch body" vs §catch-over-or "frames still in the buffer when the body runs". Exit-clear satisfies both: the handler can inspect the trace (trace.print_current() shows the chain), and the buffer is empty once the handler completes. A diverging body (raise/return) keeps/discards on its own path. - examples/243-trace-format.sx: catch handler prints the tag + the 2-frame trace, then shows the buffer is empty after. examples/241 updated: the handler now observes len=2 (was 0 under the buggy entry-clear). Gates: zig build, zig build test, bash tests/run_examples.sh (280 passed; lone failure is the user's uncommitted 213-canonical-map pack WIP). --- examples/241-error-trace-buffer.sx | 10 ++-- examples/243-trace-format.sx | 36 +++++++++++++ library/modules/trace.sx | 62 +++++++++++++++++++++++ src/ir/lower.zig | 18 +++++-- tests/expected/241-error-trace-buffer.txt | 2 +- tests/expected/243-trace-format.exit | 1 + tests/expected/243-trace-format.txt | 5 ++ 7 files changed, 124 insertions(+), 10 deletions(-) create mode 100644 examples/243-trace-format.sx create mode 100644 library/modules/trace.sx create mode 100644 tests/expected/243-trace-format.exit create mode 100644 tests/expected/243-trace-format.txt diff --git a/examples/241-error-trace-buffer.sx b/examples/241-error-trace-buffer.sx index 97f9554..db89a54 100644 --- a/examples/241-error-trace-buffer.sx +++ b/examples/241-error-trace-buffer.sx @@ -24,12 +24,14 @@ propagate :: (n: s32) -> !E { } main :: () -> s32 { - // `catch` absorbs the failure → buffer cleared before the handler runs. + // `catch` lets the handler INSPECT the trace, then absorbs: the buffer is + // cleared when the handler completes (a non-diverging exit), not on entry. + // So inside the handler the frames are still visible (here: the `raise` in + // `fail` + the `try fail` propagation in `propagate` = 2 frames)... propagate(-1) catch e { - // The pushes from `raise` + `try` were cleared on catch entry. - print("in catch: len={}\n", sx_trace_len()); // 0 + print("in catch: len={}\n", sx_trace_len()); // 2 (handler sees the chain) }; - print("after catch: len={}\n", sx_trace_len()); // 0 + print("after catch: len={}\n", sx_trace_len()); // 0 (absorbed at handler exit) // A success leaves the buffer empty (nothing pushed). propagate(1) catch e { }; diff --git a/examples/243-trace-format.sx b/examples/243-trace-format.sx new file mode 100644 index 0000000..cb95da8 --- /dev/null +++ b/examples/243-trace-format.sx @@ -0,0 +1,36 @@ +// Error return-trace formatting (ERR step E3.3). `library/modules/trace.sx` +// reads the trace buffer (E3.1, populated by E3.2's raise/try push wiring) and +// renders it. `trace.print_current()` writes the trace to stderr; the catch +// handler sees the full chain because the absorption clear fires at handler +// EXIT, not entry. Frame locations are placeholders until DWARF (ERR E3.0) +// resolves PCs to file:line; the count + ordering are already meaningful. +// +// Note: the trace goes to stderr. The test runner merges stderr+stdout, so the +// snapshot shows the trace lines interleaved with the `print` (stdout) lines. + +#import "modules/std.sx"; +trace :: #import "modules/trace.sx"; + +// Buffer length probe (the runtime symbol; public read API is the trace module). +sx_trace_len :: () -> u32 #foreign; + +E :: error { BadInput, Overflow } + +leaf :: (n: s32) -> !E { + if n < 0 { raise error.BadInput; } // pushes frame 0 + return; +} + +mid :: (n: s32) -> !E { + try leaf(n); // propagation pushes frame 1 + return; +} + +main :: () -> s32 { + mid(-1) catch e { + print("[stdout] caught {}\n", e); // tag name via the always-linked table + trace.print_current(); // [stderr] the 2-frame trace + }; + print("[stdout] recovered; trace buffer now empty (len {})\n", sx_trace_len()); + return 0; +} diff --git a/library/modules/trace.sx b/library/modules/trace.sx new file mode 100644 index 0000000..ba4cf25 --- /dev/null +++ b/library/modules/trace.sx @@ -0,0 +1,62 @@ +#import "std.sx"; + +// ===================================================================== +// trace.sx — error return-trace formatting (ERR step E3.3). +// +// Reads the thread-local return-trace buffer (ERR E3.1, populated by the +// push/clear wiring in E3.2) and renders it. A `raise` / propagating `try` +// pushes a frame; an absorbing site (`catch` / `or value` / destructure) +// clears the buffer. So at format time the buffer holds exactly the frames +// of failures that escaped to where you're formatting — typically inside a +// `catch` handler (the clear fires when the handler completes, so the body +// still sees the chain) or the (future) failable-`main` wrapper. +// +// Frame resolution: a frame is an opaque u64. Resolving it to `file:line:col` +// needs DWARF line-info (ERR E3.0), which sx does not emit yet — so for now +// each frame prints as "". The frame COUNT, ordering, +// and overflow note are already meaningful; once E3.0 lands, only the +// per-frame location string changes. (The comptime path — resolving a packed +// `(func_id, ir_offset)` via the interpreter's IR tables — also lands with the +// resolver in E3.0/E3.3-full.) +// ===================================================================== + +libc :: #library "c"; + +// The error-trace buffer C API (library/vendors/sx_trace_runtime/sx_trace.c), +// linked in for the JIT and auto-injected for AOT when traces are used. +sx_trace_len :: () -> u32 #foreign; +sx_trace_truncated :: () -> u32 #foreign; +sx_trace_frame_at :: (i: u32) -> u64 #foreign; + +write :: (fd: s32, buf: [*]u8, count: usize) -> isize #foreign libc; + +// Render the current trace buffer to a string (allocated from +// context.allocator). Empty buffer → "" so callers can cheaply skip output. +to_string :: () -> string { + n := sx_trace_len(); + if n == 0 { return ""; } + + result := "error return trace (most recent call last):\n"; + if sx_trace_truncated() != 0 { + result = concat(result, " ... older frames omitted (buffer full)\n"); + } + + i : u32 = 0; + while i < n { + frame := sx_trace_frame_at(i); + // DWARF (E3.0) will resolve `frame` to file:line:col + function name. + // Until then the raw frame value is shown (a placeholder, not a PC yet). + line := format(" frame {}: (raw {})\n", i, xx frame); + result = concat(result, line); + i = i + 1; + } + result; +} + +// Write the current trace to stderr (fd 2). No-op when the buffer is empty. +print_current :: () { + s := to_string(); + if s.len > 0 { + write(2, s.ptr, xx s.len); + } +} diff --git a/src/ir/lower.zig b/src/ir/lower.zig index 5ceb228..1af0285 100644 --- a/src/ir/lower.zig +++ b/src/ir/lower.zig @@ -15678,7 +15678,16 @@ pub const Lowering = struct { self.builder.condBr(is_err, handle_bb, &.{}, merge_bb, &.{}); self.builder.switchToBlock(handle_bb); _ = self.runCatchBody(ce, err_val, err_set, null); - if (!self.currentBlockHasTerminator()) self.builder.br(merge_bb, &.{}); + // The handler can inspect the trace (`trace.print_current()`); the + // absorption clear fires once it completes WITHOUT re-raising (a + // fall-through). A diverging body (`raise` / `return`) keeps / + // discards the buffer on its own path (ERR E3.2; reconciles + // PLAN-ERR §clear-points "cleared before body" with §catch-over-or + // "frames still in the buffer when the body runs"). + if (!self.currentBlockHasTerminator()) { + self.emitTraceClear(); + self.builder.br(merge_bb, &.{}); + } self.builder.switchToBlock(merge_bb); return self.builder.constInt(0, .void); } @@ -15715,6 +15724,9 @@ pub const Lowering = struct { } break :blk self.builder.constUndef(succ_ty); }; + // Absorption clear on a non-diverging handler (see the pure-failable + // path above): the body saw the trace, now it's consumed. + self.emitTraceClear(); self.builder.br(merge_bb, &.{bv}); } @@ -15727,10 +15739,6 @@ pub const Lowering = struct { /// catch), returns the body's value (or null if the body diverged); when /// null (pure-failable catch), runs the body for effect and returns null. fn runCatchBody(self: *Lowering, ce: *const ast.CatchExpr, err_val: Ref, err_set: TypeId, want_ty: ?TypeId) ?Ref { - // `catch` absorbs the LHS's failure: clear the trace buffer before the - // handler runs (ERR E3.2), so a failure consumed here leaves no residue. - // Runs on the error/handle path only (this fn is called from handle_bb). - self.emitTraceClear(); var handle_scope = Scope.init(self.alloc, self.scope); const saved_scope = self.scope; self.scope = &handle_scope; diff --git a/tests/expected/241-error-trace-buffer.txt b/tests/expected/241-error-trace-buffer.txt index 7436bf8..b166df5 100644 --- a/tests/expected/241-error-trace-buffer.txt +++ b/tests/expected/241-error-trace-buffer.txt @@ -1,3 +1,3 @@ -in catch: len=0 +in catch: len=2 after catch: len=0 after success: len=0 diff --git a/tests/expected/243-trace-format.exit b/tests/expected/243-trace-format.exit new file mode 100644 index 0000000..573541a --- /dev/null +++ b/tests/expected/243-trace-format.exit @@ -0,0 +1 @@ +0 diff --git a/tests/expected/243-trace-format.txt b/tests/expected/243-trace-format.txt new file mode 100644 index 0000000..b0a9c88 --- /dev/null +++ b/tests/expected/243-trace-format.txt @@ -0,0 +1,5 @@ +[stdout] caught BadInput +error return trace (most recent call last): + frame 0: (raw 1) + frame 1: (raw 1) +[stdout] recovered; trace buffer now empty (len 0)