Struct TlsRoot 

pub struct TlsRoot {
    sexp: SEXP,
}

A rooted SEXP from TLS protection.

This is similar to super::Root but without a compile-time lifetime tie to the scope. The protection is valid as long as the enclosing with_protect_scope block hasn’t exited.

Warning

Using a TlsRoot after its scope has exited is undefined behavior. The compile-time lifetime checking of super::Root is safer; use TLS convenience only when necessary.

Fields

sexp: SEXP

Implementations

impl TlsRoot

pub fn get(&self) -> SEXP

Get the underlying SEXP.

pub fn into_raw(self) -> SEXP

Consume and return the underlying SEXP.

Methods from Deref<Target = SEXP>

pub fn is_null_ptr(self) -> bool

Is this SEXP a C null pointer (address 0x0)?

This answers a pointer question, not an R question. An SEXP that R hands you (a .Call() argument, a list element, an attribute) is never a C null pointer: R’s NULL is the R_NilValue singleton, a real object at a non-zero address. A C null pointer only shows up where C code uses address zero for “nothing here”: an uninitialised static or field (SEXP::null()), an ALTREP data1/data2 slot that was never set, or an FFI function that returns NULL on failure.

To ask “is this R’s NULL?”, use SEXP::is_nil().

use miniextendr_api::SEXP;

let unset = SEXP::null();
assert!(unset.is_null_ptr());

There is no SEXP::is_null(): the name read like a test for R’s NULL, so it is gone on purpose.

use miniextendr_api::SEXP;

let unset = SEXP::null();
assert!(unset.is_null());

See also: SEXP::is_nil(), SEXP::is_null_or_nil(), SEXP::null()

pub fn is_nil(self) -> bool

Is this SEXP R’s NULL (R_NilValue)?

This is the check for an R value: an optional argument that defaults to NULL, an absent attribute, an empty list slot. It compares the address against the R_NilValue singleton and never dereferences self, so it is safe on a stale SEXP. A C null pointer is not R’s NULL; for that, use SEXP::is_null_ptr().

use miniextendr_api::SEXP;

// `x` is an argument whose R default is `NULL`: `f()` and `f(NULL)`
// both arrive as `R_NilValue`.
fn given(x: SEXP) -> bool {
    !x.is_nil()
}

See also: SEXP::nil(), SEXP::is_null_ptr(), SEXP::is_null_or_nil()

pub fn is_null_or_nil(self) -> bool

Is this SEXP either a C null pointer or R’s NULL?

For a slot that can hold either kind of “nothing”: unset (address zero) or set to R_NilValue, such as an external pointer’s protected value. For an R value alone, SEXP::is_nil() is the right check.

use miniextendr_api::SEXP;

// A slot that was never set counts as empty.
assert!(SEXP::null().is_null_or_nil());

See also: SEXP::is_nil(), SEXP::is_null_ptr()

pub fn as_ptr(self) -> *mut SEXPREC

Get the raw pointer.

pub unsafe fn altrep_data1_raw(self) -> SEXP

Get the raw SEXP in the ALTREP data1 slot.

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

pub unsafe fn altrep_data1_raw_unchecked(self) -> SEXP

Get the raw SEXP in the ALTREP data1 slot (unchecked — no thread routing).

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

pub unsafe fn set_altrep_data1(self, v: SEXP)

Set the ALTREP data1 slot.

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

pub unsafe fn altrep_data2_raw(self) -> SEXP

Get the raw SEXP in the ALTREP data2 slot.

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

pub unsafe fn altrep_data2_raw_unchecked(self) -> SEXP

Get the raw SEXP in the ALTREP data2 slot (unchecked — no thread routing).

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

pub unsafe fn set_altrep_data2(self, v: SEXP)

Set the ALTREP data2 slot.

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

pub unsafe fn set_altrep_data2_unchecked(self, v: SEXP)

Set the ALTREP data2 slot (unchecked — no thread routing).

Safety

• self must be a valid ALTREP SEXP
• Must be called from the R main thread

Trait Implementations

impl Clone for TlsRoot

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for TlsRoot

impl Deref for TlsRoot

type Target = SEXP

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl TrivialClone for TlsRoot

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: 8 bytes