Expand description
R’s main thread, and advanced controls for R’s process-global C-stack bounds.
§R’s main thread
R’s C API may only be called on R’s main thread: the thread that loaded the
package and ran miniextendr_runtime_init from R_init_<pkg>. Every
generated .Call entry point, ALTREP callback and connection callback runs
there.
is_r_main_thread— whether the current thread is R’s main thread.with_r_thread— run a closure that calls R, after checking that this is R’s main thread. The checked FFI bindings incrate::sysgo through it, so an R call from a Rayon orstd::threadthread panics with a clear message instead of reaching R.
Inside a with_r_thread body the check has been made: the
*_unchecked variants in crate::sys are fine there (the lint
MXL301 recognises the body, alongside ALTREP callbacks and
crate::unwind_protect::with_r_unwind_protect bodies).
Threads the package spawns stay pure Rust: compute there, then hand the
results to R on the main thread (see rayon_bridge for the pattern).
§R API calls remain main-thread-only
R’s stack checking mechanism causes segfaults when R API functions are called from threads other than the main R thread. This module also exposes legacy tools that disable that one check, but doing so does not make R’s API safe on a secondary thread.
R’s global state, garbage collector, and error signaling are not made
thread-safe by changing R_CStackLimit. Writing R Extensions requires
package R API calls to stay on R’s main thread and specifically says packages
must not change these variables to call stack-checking internals on a
secondary thread. Do not use this module as an off-main R bridge in package
code. The misleading package-facing surface is tracked for removal or
relocation in #1352.
StackCheckGuard is gated behind the nonapi feature because it
mutates R_CStackStart / R_CStackLimit / R_CStackDir, none of which
are part of R’s public C API. The lint MXL301 currently recognizes this
guard as an unchecked-FFI context, but that only reflects the existing API;
it does not override R’s main-thread contract.
§Don’t use Rf_error here either
A longjmp from a non-main thread is undefined behaviour even with the
stack check disabled. Panic, capture the message in your guard’s
fallback (see crate::ffi_guard::guarded_ffi_call_with_fallback), and
surface the failure to the main thread before letting R see it. The lint
MXL300 rejects direct Rf_error calls in user code.
§Cross references
crate::sys— checked vs*_uncheckedFFI surface.crate::ffi_guard— guard taxonomy across boundaries.
§Background
R tracks three variables for stack overflow detection (all non-API):
R_CStackStart- top of the main thread’s stackR_CStackLimit- stack size limitR_CStackDir- stack growth direction
When R API functions check the stack, they compare the current stack pointer against these bounds. On a different thread, the stack is completely different, causing false stack overflow detection.
§Solution
Setting R_CStackLimit to usize::MAX disables R’s own stack-address
check. The OS still enforces its real stack limit, but all other R threading
invariants remain unchanged.
§Example
use miniextendr_api::thread::StackCheckGuard;
// Advanced embedded-host bookkeeping only; not package R API access.
let _guard = StackCheckGuard::disable();
assert!(miniextendr_api::thread::is_stack_checking_disabled());§Feature Gate
The stack-check controls require the nonapi feature because they access
non-API R internals (R_CStackLimit, R_CStackStart, R_CStackDir).
Re-exports§
Structs§
- RThread
Builder - Builder for spawning pure-Rust threads with a legacy R-sized stack.
Constants§
- DEFAULT_
R_ STACK_ SIZE - Default stack size for the legacy R-sized thread builder (8 MiB).
Statics§
Functions§
- assert_
runtime_ 🔒initialized - Panic if the runtime hasn’t been initialized.
- is_
r_ main_ thread - Check if the current thread is R’s main thread.
- miniextendr_
runtime_ 👻init - Initialize the miniextendr runtime: record the calling thread as R’s main thread, and open there the channels that bring it the deferred conditions queued on other threads and the R exits dropped on them.
- miniextendr_
runtime_ 👻shutdown - Shut the miniextendr runtime down: uninstall the process panic hook this
DLL registered (see
backtrace::miniextendr_panic_hook_uninstall). - with_
r_ thread - Run a closure that calls R’s C API, after checking that this is R’s main thread.