Struct RngGuard 

pub struct RngGuard {
    saves: bool,
    _nosend: PhantomData<Rc<()>>,
}

Proof that R’s RNG state is loaded on R’s main thread, and the way to draw from it.

A guard from RngGuard::new or with_rng calls GetRNGstate() when it is created and PutRNGstate() when it drops, so the state is saved even if the function panics or returns early. The draws (unif_rand, norm_rand, exp_rand, unif_index) borrow the guard, so none can run outside its scope. The guard is !Send and !Sync, so a draw can’t run on another thread either.

Example

use miniextendr_api::rng::RngGuard;

fn generate_uniform() -> f64 {
    // SAFETY: called on R's main thread.
    let rng = unsafe { RngGuard::new() };
    rng.unif_rand()
}

Warning: R Longjumps

This guard relies on Rust’s drop semantics. If R triggers a longjmp (via Rf_error etc.), the destructor will NOT run unless the code is wrapped in with_r_unwind_protect. For functions exposed to R, prefer using #[miniextendr(rng)] which handles this correctly.

Fields

saves: bool

Whether dropping the guard saves the state (PutRNGstate()). False only for the guard a #[miniextendr(rng)] wrapper hands the body, whose state the wrapper saves itself.

_nosend: PhantomData<Rc<()>>

Implementations

impl RngGuard

pub unsafe fn new() -> Self

Create a new RNG guard, loading the current RNG state.

Calls GetRNGstate() to load R’s .Random.seed into the RNG.

Safety

Must be called from R’s main thread — R’s RNG state and the underlying GetRNGstate() / PutRNGstate() calls are only valid there. Calling this off the main thread is undefined behaviour. There is deliberately no Default impl: constructing a guard is an unsafe, thread-scoped act, not a safe default (#1096).

#[doc(hidden)]

pub unsafe fn __mx_loaded_by_wrapper() -> Self

The guard a #[miniextendr(rng)] wrapper passes to a &RngGuard parameter. Generated code only.

Safety

Must be called on R’s main thread while the caller holds the state loaded (GetRNGstate() has run) and saves it with PutRNGstate() after the guard drops: dropping this guard saves nothing.

pub fn unif_rand(&self) -> f64

A uniform draw on (0, 1): R’s unif_rand(), what runif(1) draws.

pub fn norm_rand(&self) -> f64

A standard normal draw: R’s norm_rand(), what rnorm(1) draws.

pub fn exp_rand(&self) -> f64

A standard exponential draw (rate 1): R’s exp_rand(), what rexp(1) draws.

pub fn unif_index(&self, n: f64) -> f64

A uniform integer on [0, n), as a double: R’s R_unif_index(n), the draw behind sample(). It uses the sample kind RNGkind() selects, so unif_index(n) + 1 draws what sample.int(n, 1) draws. Take n > 0.

Trait Implementations

impl Debug for RngGuard

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for RngGuard

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 1 byte