Skip to main content

Module thread

Module thread 

Source
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 in crate::sys go through it, so an R call from a Rayon or std::thread thread 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

§Background

R tracks three variables for stack overflow detection (all non-API):

  • R_CStackStart - top of the main thread’s stack
  • R_CStackLimit - stack size limit
  • R_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§

use std::sync::OnceLock; 🔒
use std::thread::ThreadId; 🔒

Structs§

RThreadBuilder
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§

R_MAIN_THREAD_ID 🔒

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.