Expand description
Structured panic telemetry for debugging Rust panics that become R errors.
Three separate panic→R-error paths exist in miniextendr (ALTREP trampolines, connection callbacks, and unwind_protect). This module provides a unified hook point that fires before each panic is converted to an R error.
§Relationship to the three emission paths
This module is observability, not emission. It does not raise R
conditions and does not change how panics become errors; it only lets a
caller observe them. The three actual emission paths are documented on
crate::error_value:
panic!(msg)— escape hatch; tagged-SEXP withkind = "panic".crate::error!/crate::warning!/crate::message!/crate::condition!— typed conditions viaRConditionpanic payloads.Result<_, E: std::error::Error>withcrate::condition::AsRError— value-style propagation; tagged-SEXP withkind = "result_err".
fire is invoked from each catch site before the panic message is encoded
into a tagged condition value, so a registered hook sees every Rust-origin
failure regardless of which of the three paths produced it. Typical uses:
routing to tracing / log, capturing stack snapshots for crash reports,
or surfacing the panic message in test harnesses where R’s stderr is
buffered. The hook must not raise R conditions itself (it runs inside the
panic-handling path) and must not panic — secondary panics from the hook
are caught and silently suppressed by fire (this crate, pub(crate)).
§Usage
use miniextendr_api::panic_telemetry::{set_panic_telemetry_hook, PanicReport, PanicSource};
set_panic_telemetry_hook(|report| {
eprintln!("[{:?}] panic: {}", report.source, report.message);
});§Threads
Every panic→R-error boundary runs on R’s main thread, so the hook lives
there: a thread-local slot, set and fired on that thread, and the closure
need not be Send or Sync. A hook set on another thread stays in that
thread’s slot and never sees the main thread’s panics.
§Performance
fire() reads a thread-local slot and, with a hook set, clones its Rc.
The hook only fires on panic paths, never on hot paths.
Re-exports§
use std::cell::RefCell;🔒use std::panic::AssertUnwindSafe;🔒use std::panic::catch_unwind;🔒use std::rc::Rc;🔒
Structs§
- Panic
Report - A structured panic report passed to the telemetry hook.
Enums§
- Panic
Source - Describes where a panic originated before being converted to an R error.
Constants§
- HOOK 🔒
Functions§
- clear_
panic_ telemetry_ hook - Remove the current panic telemetry hook, if any.
- fire 🔒
- Fire the telemetry hook if one is set.
- set_
panic_ telemetry_ hook - Register a panic telemetry hook on R’s main thread.
Type Aliases§
- Hook 🔒