miniextendr_api/ffi_guard.rs
1//! Unified FFI guard for catching panics at Rust-R boundaries.
2//!
3//! Three modules independently catch panics at FFI boundaries:
4//! `altrep_bridge.rs`, `unwind_protect.rs`, and `connection.rs`. This module
5//! extracts the common pattern into a single `guarded_ffi_call` function.
6//!
7//! Most user code never calls anything here. The proc-macro layer
8//! (`#[miniextendr]`) inserts the right guard at every Rust → R boundary it
9//! generates. Reach for these helpers when you're writing a callback or
10//! trampoline that the macros don't already cover (custom connections,
11//! manual ALTREP, raw FFI shims).
12//!
13//! ## Guard Modes
14//!
15//! - [`GuardMode::CatchUnwind`]: Wraps the closure in `catch_unwind`. On panic,
16//! fires telemetry and raises an R error via `Rf_error` (diverges).
17//! Used by ALTREP `RustUnwind` callbacks.
18//!
19//! - [`GuardMode::RUnwind`]: Uses `R_UnwindProtect` to catch both Rust panics
20//! and R longjmps. Used by ALTREP callbacks that call R APIs. Routes
21//! through `crate::unwind_protect::with_r_unwind_protect_sourced`
22//! (crate-private).
23//!
24//! The ALTREP-specific `Unsafe` mode (no protection at all) stays in
25//! `altrep_bridge.rs` since it has no general applicability.
26//!
27//! ## Tradeoffs vs raising R errors directly
28//!
29//! Don't reach for `Rf_error` / `Rf_errorcall` to fail out of a callback —
30//! the longjmp skips Rust destructors and the lint **MXL300** rejects it.
31//! Panic instead; whichever guard mode you pick converts the panic into the
32//! tagged-condition transport ([`crate::error_value`]) or, on the ALTREP
33//! `RUnwind` path, raises the same structured `rust_*` condition via the
34//! crate-private `raise_rust_condition_via_stop` helper.
35//!
36//! ## Cross references
37//!
38//! - [`crate::with_r_thread`] — the main-thread check.
39//! - [`crate::unwind_protect::with_r_unwind_protect`] — the user-facing R
40//! error catcher; consumed by `RUnwind` mode.
41
42use std::panic::{AssertUnwindSafe, catch_unwind};
43
44use crate::panic_telemetry::PanicSource;
45use crate::unwind_protect::panic_payload_to_string;
46
47/// FFI guard mode controlling how panics are caught at Rust-R boundaries.
48#[derive(Debug, Clone, Copy, PartialEq, Eq)]
49pub enum GuardMode {
50 /// `catch_unwind` only. On panic: fire telemetry, then `Rf_error` (diverges).
51 ///
52 /// Use when R longjmps cannot occur (the closure does not call R APIs).
53 CatchUnwind,
54 /// `R_UnwindProtect`. Catches both Rust panics and R longjmps.
55 ///
56 /// Use when the closure may call R APIs that can error.
57 RUnwind,
58}
59
60/// Execute `f` inside an FFI guard selected by `mode`.
61///
62/// On panic:
63/// - Extracts the panic message from the payload.
64/// - Fires [`crate::panic_telemetry`] with `source`.
65/// - For [`GuardMode::CatchUnwind`]: raises R error via `Rf_error` (diverges — never returns).
66/// - For [`GuardMode::RUnwind`]: delegates to `with_r_unwind_protect_sourced`.
67///
68/// Deferred conditions signal on R's main thread before return (or panic
69/// conversion). Use this boundary on the main thread. Any SEXP held in the
70/// generic result must be rooted, e.g. by returning `OwnedProtect`.
71///
72/// # Parameters
73///
74/// - `f`: The closure to execute.
75/// - `mode`: Which guard strategy to use.
76/// - `source`: Attribution for telemetry if a panic occurs.
77///
78/// # Note on `fallback`
79///
80/// `GuardMode::CatchUnwind` diverges on panic (`Rf_error` never returns), so no
81/// fallback value is needed. If you need a fallback (e.g. connection trampolines
82/// that must return a value on panic without calling R), use
83/// [`guarded_ffi_call_with_fallback`] instead.
84#[inline]
85pub fn guarded_ffi_call<F, R>(f: F, mode: GuardMode, source: PanicSource) -> R
86where
87 F: FnOnce() -> R,
88{
89 match mode {
90 GuardMode::CatchUnwind => {
91 let mark = crate::deferred_condition::mark();
92 let boundary = crate::unwind_protect::Boundary::enter();
93 let outcome = catch_unwind(AssertUnwindSafe(f)).map_err(|payload| {
94 // An R exit carried out of an evaluation (#1835) continues in R.
95 // SAFETY: a callback boundary on R's main thread.
96 let payload =
97 unsafe { crate::unwind_protect::resume_if_r_unwind(payload, mark, &boundary) };
98 crate::unwind_protect::panic_message_with_location(payload.as_ref())
99 });
100 drop(boundary);
101 match crate::deferred_condition::finish_guarded(mark, outcome) {
102 Ok(val) => val,
103 Err(msg) => {
104 crate::panic_telemetry::fire(&msg, source);
105 crate::error::r_stop(&msg)
106 }
107 }
108 }
109 GuardMode::RUnwind => crate::unwind_protect::with_r_unwind_protect_sourced(f, None, source),
110 }
111}
112
113/// Execute `f` inside a `CatchUnwind` guard, returning `fallback` on panic.
114///
115/// Unlike [`guarded_ffi_call`] with `CatchUnwind` (which diverges via `Rf_error`),
116/// this variant returns the `fallback` value instead of raising an R error.
117/// This is needed for connection trampolines where panicking through R/C frames
118/// is UB but raising an R error is also undesirable (the caller expects a return
119/// value indicating failure).
120///
121/// Deferred conditions are signalled on R's main thread after the callback.
122/// R handlers may exit (including `options(warn = 2)`); the Rust panic fallback
123/// is unchanged. Finalizer callbacks must suppress conditions instead.
124/// Telemetry is fired before returning the fallback.
125#[inline]
126pub fn guarded_ffi_call_with_fallback<F, R>(f: F, fallback: R, source: PanicSource) -> R
127where
128 F: FnOnce() -> R,
129{
130 let mark = crate::deferred_condition::mark();
131 let boundary = crate::unwind_protect::Boundary::enter();
132 let outcome = match catch_unwind(AssertUnwindSafe(f)) {
133 Ok(value) => Ok(value),
134 Err(payload) => {
135 let payload = match payload.downcast::<crate::unwind_protect::RUnwind>() {
136 // An R exit carried out of an evaluation (#1835) continues in R.
137 Ok(exit) if exit.belongs_to(&boundary) => {
138 drop(fallback);
139 crate::deferred_condition::discard(mark);
140 boundary.leave();
141 // SAFETY: a callback boundary on R's main thread.
142 unsafe { (*exit).resume() }
143 }
144 Ok(exit) => exit.stray(),
145 Err(payload) => payload,
146 };
147 Err(panic_payload_to_string(payload.as_ref()).into_owned())
148 }
149 };
150 drop(boundary);
151 let (outcome, fallback) = crate::deferred_condition::finish_guarded(mark, (outcome, fallback));
152 match outcome {
153 Ok(val) => val,
154 Err(msg) => {
155 crate::panic_telemetry::fire(&msg, source);
156 fallback
157 }
158 }
159}
160
161#[cfg(test)]
162mod tests;