Struct Protected 

pub struct Protected<'a, T> {
    inner: T,
    _protect: Option<OwnedProtect>,
    _marker: PhantomData<&'a ()>,
}

A Rust value (T) bundled with an OwnedProtect guard on an SEXP the value borrows from. The protect releases on drop; the lifetime ties any borrows inside T to &self, so T’s SEXP-internal references can’t outlive the protection.

When to use Protected<'a, T> vs the alternatives

Pattern	Use	Why
OwnedProtect	raw SEXP, no Rust view	one-shot protect/unprotect on a single SEXP
ProtectScope + Root	several SEXPs in one function body	batched UNPROTECT, no Rust view
Protected<'a, T>	SEXP + Rust view of its data	pairs a root with T; does not constrain references inside T

Lifetimes and thread affinity

This generic bundle does not shorten lifetimes inside T. Its callers must avoid exposing an inner borrowed view after the root is released; use a concrete owner with accessors tied to &self (such as ProtectedStrVec) for that guarantee. Option<OwnedProtect> is !Send + !Sync even when its value is None; the trusted constructor does not change those auto-trait properties.

Fields

inner: T

_protect: Option<OwnedProtect>

_marker: PhantomData<&'a ()>

Implementations

impl<'a, T> Protected<'a, T>

pub unsafe fn new(sexp: SEXP, inner: T) -> Self

Create a protected bundle. Calls Rf_protect on sexp.

inner may borrow from sexp, but this bundle does not rewrite those lifetimes. The caller must ensure any references copied from inner remain valid, including after this root is dropped.

Safety

• Must be called from the R main thread.
• sexp must be a valid SEXP.
• Borrowed data in inner must remain valid for its declared lifetime; this guard alone cannot guarantee that when T exposes a longer reference (for example, T = &'static str).

Example

use miniextendr_api::{Protected, OwnedProtect};
use miniextendr_api::prelude::SEXP;

unsafe fn wrap_view(sexp: SEXP, view: MyView<'_>) -> Protected<'_, MyView<'_>> {
    // Protect the SEXP and bundle it with the view.
    // The caller must keep any references exposed by MyView valid.
    Protected::new(sexp, view)
}

pub unsafe fn from_trusted(_sexp: SEXP, inner: T) -> Self

Create a protected bundle without adding to the protect stack.

Use when sexp is already protected by R (a .Call argument, a ProtectScope slot, an enclosing OwnedProtect) to avoid double-protecting. As with new, 'a does not narrow references contained in T.

Safety

• Must be called from the R main thread.
• sexp must be a valid SEXP.
• sexp must remain GC-protected for the lifetime of the returned Protected.
• Lifetime contract same as Protected::new.

pub fn get(&self) -> &T

Borrow the inner view.

pub fn into_inner(self) -> T

Consume the bundle and return the inner view.

The OwnedProtect guard drops here, releasing the SEXP from the protect stack. Any owned data extracted from T must not retain SEXP references after this point.

Trait Implementations

impl<'a, T: Debug> Debug for Protected<'a, T>

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

Formats the value using the given formatter.

impl<'a, T> Deref for Protected<'a, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

Layout

Note: Unable to compute type layout, possibly due to this type having generic parameters. Layout can only be computed for concrete, fully-instantiated types.