miniextendr_api/
altrep_sexp.rs

1//! `AltrepSexp` — a `!Send + !Sync` wrapper for ALTREP vectors.
2//!
3//! R uses ALTREP (Alternative Representations) for common idioms like `1:N`,
4//! `seq_len(N)`, and `as.character(1:N)`. These vectors are lazily materialized:
5//! calling `DATAPTR_RO` triggers allocation, GC, and C callbacks inside R's
6//! runtime. This must only happen on the R main thread.
7//!
8//! This module provides two complementary tools:
9//!
10//! - **[`AltrepSexp`]** — a `!Send + !Sync` wrapper that holds an ALTREP SEXP
11//!   and prevents it from crossing thread boundaries at compile time.
12//! - **[`ensure_materialized`]** — a function that forces materialization if
13//!   the SEXP is ALTREP, returning a SEXP with a stable data pointer.
14//!
15//! Plain (non-ALTREP) SEXPs are `Send + Sync` and are unaffected by either.
16//!
17//! # How ALTREP flows through miniextendr
18//!
19//! | Parameter type | ALTREP handling |
20//! |---|---|
21//! | Typed (`Vec<i32>`, `&[f64]`) | Auto-materialized via `DATAPTR_RO` in `TryFromSexp` |
22//! | `SEXP` | Auto-materialized via [`ensure_materialized`] in `TryFromSexp` |
23//! | [`AltrepSexp`] | Wrapped without materializing. `!Send + !Sync`. |
24//! | `extern "C-unwind"` raw SEXP | No conversion — receives raw SEXP as-is |
25//!
26//! # Usage
27//!
28//! ```ignore
29//! use miniextendr_api::AltrepSexp;
30//!
31//! // As a #[miniextendr] parameter — accepts only ALTREP vectors:
32//! #[miniextendr]
33//! pub fn altrep_length(x: AltrepSexp) -> usize {
34//!     x.len()
35//! }
36//!
37//! // Manual wrapping:
38//! if let Some(altrep) = AltrepSexp::try_wrap(sexp) {
39//!     // Must materialize on R main thread before accessing data
40//!     let materialized: SEXP = unsafe { altrep.materialize() };
41//! }
42//!
43//! // Or use the convenience helper on any SEXP:
44//! let safe_sexp = unsafe { ensure_materialized(sexp) };
45//! ```
46//!
47//! See also: `docs/ALTREP_SEXP.md` for the full guide on receiving ALTREP
48//! vectors from R.
49
50use crate::ffi::{self, Rcomplex, SEXP, SEXPTYPE, SexpExt};
51use crate::from_r::r_slice;
52use std::marker::PhantomData;
53use std::rc::Rc;
54
55/// A SEXP known to be ALTREP. `!Send + !Sync` — must be materialized on the
56/// R main thread before data can be accessed or sent to other threads.
57///
58/// This type prevents ALTREP vectors from being accidentally sent to rayon
59/// or other worker threads where `DATAPTR_RO` would invoke R internals
60/// (undefined behavior).
61///
62/// # As a `#[miniextendr]` parameter
63///
64/// `AltrepSexp` implements [`TryFromSexp`](crate::from_r::TryFromSexp), so it
65/// can be used directly as a function parameter. It **only accepts ALTREP
66/// vectors** — non-ALTREP input produces an error.
67///
68/// ```ignore
69/// #[miniextendr]
70/// pub fn altrep_info(x: AltrepSexp) -> String {
71///     format!("{:?}, len={}", x.sexptype(), x.len())
72/// }
73/// ```
74///
75/// ```r
76/// altrep_info(1:10)          # OK — 1:10 is ALTREP
77/// altrep_info(c(1L, 2L, 3L)) # Error: "expected an ALTREP vector"
78/// ```
79///
80/// # Construction
81///
82/// - [`AltrepSexp::try_wrap`] — runtime check, returns `None` if not ALTREP
83/// - [`AltrepSexp::from_raw`] — unsafe, caller asserts `ALTREP(sexp) != 0`
84///
85/// # Materialization
86///
87/// All materialization methods must be called on the R main thread.
88///
89/// - [`AltrepSexp::materialize`] — forces R to materialize, returns plain SEXP
90/// - [`AltrepSexp::materialize_integer`] — materialize INTSXP and return `&[i32]`
91/// - [`AltrepSexp::materialize_real`] — materialize REALSXP and return `&[f64]`
92/// - [`AltrepSexp::materialize_logical`] — materialize LGLSXP and return `&[i32]`
93/// - [`AltrepSexp::materialize_raw`] — materialize RAWSXP and return `&[u8]`
94/// - [`AltrepSexp::materialize_complex`] — materialize CPLXSXP and return `&[Rcomplex]`
95/// - [`AltrepSexp::materialize_strings`] — materialize STRSXP to `Vec<Option<String>>`
96///
97/// # Thread safety
98///
99/// `AltrepSexp` is `!Send + !Sync` (via `PhantomData<Rc<()>>`). This is a
100/// compile-time guarantee: you cannot send an un-materialized ALTREP vector
101/// to another thread. Call one of the `materialize_*` methods first to get
102/// a `Send + Sync` slice or SEXP.
103pub struct AltrepSexp {
104    sexp: SEXP,
105    /// PhantomData<Rc<()>> makes this type !Send + !Sync.
106    _not_send: PhantomData<Rc<()>>,
107}
108
109impl AltrepSexp {
110    /// Wrap a SEXP that is known to be ALTREP.
111    ///
112    /// # Safety
113    ///
114    /// Caller must ensure `ALTREP(sexp)` is true (non-zero).
115    #[inline]
116    pub unsafe fn from_raw(sexp: SEXP) -> Self {
117        debug_assert!(sexp.is_altrep());
118        Self {
119            sexp,
120            _not_send: PhantomData,
121        }
122    }
123
124    /// Check a SEXP and wrap if ALTREP. Returns `None` if not ALTREP.
125    #[inline]
126    pub fn try_wrap(sexp: SEXP) -> Option<Self> {
127        if sexp.is_altrep() {
128            Some(Self {
129                sexp,
130                _not_send: PhantomData,
131            })
132        } else {
133            None
134        }
135    }
136
137    /// Force materialization and return the (now materialized) SEXP.
138    ///
139    /// For contiguous types (INTSXP, REALSXP, LGLSXP, RAWSXP, CPLXSXP),
140    /// calls `DATAPTR_RO` to trigger ALTREP materialization.
141    /// For STRSXP, iterates `STRING_ELT` to force element materialization.
142    ///
143    /// After this call, the SEXP's data pointer is stable and can be safely
144    /// accessed from any thread (the SEXP itself is still `Send + Sync`).
145    ///
146    /// # Safety
147    ///
148    /// Must be called on the R main thread.
149    pub unsafe fn materialize(self) -> SEXP {
150        let typ = self.sexp.type_of();
151        match typ {
152            SEXPTYPE::STRSXP => {
153                let n = self.sexp.xlength();
154                for i in 0..n {
155                    let _ = self.sexp.string_elt(i);
156                }
157            }
158            SEXPTYPE::INTSXP
159            | SEXPTYPE::REALSXP
160            | SEXPTYPE::LGLSXP
161            | SEXPTYPE::RAWSXP
162            | SEXPTYPE::CPLXSXP => {
163                let _ = unsafe { ffi::DATAPTR_RO(self.sexp) };
164            }
165            _ => {} // non-vector types, nothing to materialize
166        }
167        self.sexp
168    }
169
170    /// Materialize and return a typed slice of `f64` (REALSXP).
171    ///
172    /// # Safety
173    ///
174    /// Must be called on the R main thread. The SEXP must be REALSXP.
175    pub unsafe fn materialize_real(&self) -> &[f64] {
176        let ptr = unsafe { ffi::DATAPTR_RO(self.sexp) } as *const f64;
177        let len = self.sexp.len();
178        unsafe { r_slice(ptr, len) }
179    }
180
181    /// Materialize and return a typed slice of `i32` (INTSXP).
182    ///
183    /// # Safety
184    ///
185    /// Must be called on the R main thread. The SEXP must be INTSXP.
186    pub unsafe fn materialize_integer(&self) -> &[i32] {
187        let ptr = unsafe { ffi::DATAPTR_RO(self.sexp) } as *const i32;
188        let len = self.sexp.len();
189        unsafe { r_slice(ptr, len) }
190    }
191
192    /// Materialize and return a typed slice of `i32` (LGLSXP, R's internal logical storage).
193    ///
194    /// # Safety
195    ///
196    /// Must be called on the R main thread. The SEXP must be LGLSXP.
197    pub unsafe fn materialize_logical(&self) -> &[i32] {
198        let ptr = unsafe { ffi::DATAPTR_RO(self.sexp) } as *const i32;
199        let len = self.sexp.len();
200        unsafe { r_slice(ptr, len) }
201    }
202
203    /// Materialize and return a typed slice of `u8` (RAWSXP).
204    ///
205    /// # Safety
206    ///
207    /// Must be called on the R main thread. The SEXP must be RAWSXP.
208    pub unsafe fn materialize_raw(&self) -> &[u8] {
209        let ptr = unsafe { ffi::DATAPTR_RO(self.sexp) } as *const u8;
210        let len = self.sexp.len();
211        unsafe { r_slice(ptr, len) }
212    }
213
214    /// Materialize and return a typed slice of `Rcomplex` (CPLXSXP).
215    ///
216    /// # Safety
217    ///
218    /// Must be called on the R main thread. The SEXP must be CPLXSXP.
219    pub unsafe fn materialize_complex(&self) -> &[Rcomplex] {
220        let ptr = unsafe { ffi::DATAPTR_RO(self.sexp) } as *const Rcomplex;
221        let len = self.sexp.len();
222        unsafe { r_slice(ptr, len) }
223    }
224
225    /// Materialize strings into owned Rust data.
226    ///
227    /// Each element is `None` for `NA_character_`, or `Some(String)` otherwise.
228    ///
229    /// # Safety
230    ///
231    /// Must be called on the R main thread. The SEXP must be STRSXP.
232    pub unsafe fn materialize_strings(&self) -> Vec<Option<String>> {
233        use crate::from_r::charsxp_to_str;
234        let n = self.sexp.len();
235        let mut out = Vec::with_capacity(n);
236        for i in 0..n {
237            let elt = self.sexp.string_elt(i as ffi::R_xlen_t);
238            if elt == SEXP::na_string() {
239                out.push(None);
240            } else {
241                out.push(Some(unsafe { charsxp_to_str(elt) }.to_owned()));
242            }
243        }
244        out
245    }
246
247    /// Get the inner SEXP without materializing.
248    ///
249    /// # Safety
250    ///
251    /// The returned SEXP is still ALTREP. Do not call `DATAPTR_RO` on it
252    /// from a non-R thread.
253    #[inline]
254    pub unsafe fn as_raw(&self) -> SEXP {
255        self.sexp
256    }
257
258    /// Get the SEXPTYPE of the underlying vector.
259    #[inline]
260    pub fn sexptype(&self) -> SEXPTYPE {
261        self.sexp.type_of()
262    }
263
264    /// Get the length of the underlying vector.
265    #[inline]
266    pub fn len(&self) -> usize {
267        self.sexp.len()
268    }
269
270    /// Check if the underlying vector is empty.
271    #[inline]
272    pub fn is_empty(&self) -> bool {
273        self.len() == 0
274    }
275}
276
277/// Conversion from R SEXP to `AltrepSexp`.
278///
279/// Only succeeds if the input is an ALTREP vector (`ALTREP(sexp) != 0`).
280/// Non-ALTREP input produces `SexpError::InvalidValue`.
281///
282/// This is the inverse of [`TryFromSexp for SEXP`](crate::from_r::TryFromSexp),
283/// which accepts any SEXP but auto-materializes ALTREP.
284impl crate::from_r::TryFromSexp for AltrepSexp {
285    type Error = crate::from_r::SexpError;
286
287    #[inline]
288    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
289        AltrepSexp::try_wrap(sexp).ok_or_else(|| {
290            crate::from_r::SexpError::InvalidValue(
291                "expected an ALTREP vector but got a non-ALTREP SEXP".to_string(),
292            )
293        })
294    }
295
296    #[inline]
297    unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
298        Self::try_from_sexp(sexp)
299    }
300}
301
302impl std::fmt::Debug for AltrepSexp {
303    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
304        f.debug_struct("AltrepSexp")
305            .field("sexptype", &self.sexptype())
306            .field("len", &self.len())
307            .finish()
308    }
309}
310
311/// If `sexp` is ALTREP, force materialization and return the SEXP.
312/// If not ALTREP, return as-is (no-op).
313///
314/// This is the main entry point for ensuring a SEXP is safe to access
315/// from non-R threads. After materialization, the data pointer is stable
316/// and the SEXP can be freely sent across threads.
317///
318/// Called automatically by `TryFromSexp for SEXP` — you only need to call
319/// this directly in `extern "C-unwind"` functions that receive raw SEXPs.
320///
321/// For contiguous types (INTSXP, REALSXP, LGLSXP, RAWSXP, CPLXSXP),
322/// calls `DATAPTR_RO` to trigger materialization. For STRSXP, iterates
323/// `STRING_ELT` to force each element to materialize.
324///
325/// # Safety
326///
327/// Must be called on the R main thread (materialization invokes R internals).
328#[inline]
329pub unsafe fn ensure_materialized(sexp: SEXP) -> SEXP {
330    if sexp.is_altrep() {
331        unsafe { AltrepSexp::from_raw(sexp).materialize() }
332    } else {
333        sexp
334    }
335}
336
337// Compile-time assertions: SEXP must remain Send + Sync.
338const _: () = {
339    fn _assert_send<T: Send>() {}
340    fn _assert_sync<T: Sync>() {}
341
342    fn _sexp_is_send_sync() {
343        _assert_send::<SEXP>();
344        _assert_sync::<SEXP>();
345    }
346};
347
348#[cfg(test)]
349mod tests {
350    use super::*;
351
352    /// Verify AltrepSexp is !Send and !Sync at compile time.
353    /// SEXP IS Send + Sync.
354    fn _assert_send_sync_properties() {
355        fn requires_send<T: Send>() {}
356        fn requires_sync<T: Sync>() {}
357
358        // These must NOT compile — uncomment to verify:
359        // requires_send::<AltrepSexp>();
360        // requires_sync::<AltrepSexp>();
361
362        // SEXP IS Send + Sync:
363        requires_send::<SEXP>();
364        requires_sync::<SEXP>();
365    }
366}
miniextendr_api/altrep_sexp.rs

miniextendr_api/
altrep_sexp.rs
