miniextendr_api/
cached_class.rs

1//! Cached R class attribute SEXPs.
2//!
3//! Frequently-used class vectors (like `c("POSIXct", "POSIXt")`) and attribute
4//! values are allocated once and preserved permanently. This avoids repeated
5//! `Rf_mkCharLenCE` hash lookups on hot paths.
6//!
7//! Two declarative macros handle the boilerplate:
8//!
9//! ```ignore
10//! // Cache a symbol (Rf_install result):
11//! cached_symbol!(pub(crate) fn tzone_symbol() = c"tzone");
12//!
13//! // Cache a STRSXP vector (class, names, etc.):
14//! cached_strsxp!(pub(crate) fn posixct_class_sexp() = [c"POSIXct", c"POSIXt"]);
15//! cached_strsxp!(pub(crate) fn date_class_sexp() = [c"Date"]);
16//! ```
17//!
18//! Both expand to a function with a `static OnceLock<SEXP>` inside.
19//! First call initializes; subsequent calls are a single atomic load.
20//!
21//! CHARSXPs are obtained via `Rf_install` + `PRINTNAME` — symbols are never
22//! collected, so the CHARSXP is permanently valid. STRSXP vectors are kept
23//! alive via `R_PreserveObject`.
24
25// region: Macros
26
27/// Cache an `Rf_install` symbol result.
28///
29/// Expands to a function that returns the cached SEXP. First call does the
30/// `Rf_install`; subsequent calls are a single atomic load.
31///
32/// ```ignore
33/// cached_symbol!(pub(crate) fn tzone_symbol() = c"tzone");
34///
35/// // With feature gate:
36/// cached_symbol!(#[cfg(feature = "time")] pub(crate) fn tzone_symbol() = c"tzone");
37/// ```
38macro_rules! cached_symbol {
39    ($(#[$meta:meta])* $vis:vis fn $name:ident() = $cstr:expr) => {
40        $(#[$meta])*
41        $vis fn $name() -> $crate::ffi::SEXP {
42            static CACHE: ::std::sync::OnceLock<$crate::ffi::SEXP> = ::std::sync::OnceLock::new();
43            *CACHE.get_or_init(|| unsafe { $crate::ffi::Rf_install($cstr.as_ptr()) })
44        }
45    };
46}
47#[allow(unused_imports)] // exported for use by other modules
48pub(crate) use cached_symbol;
49
50/// Cache a STRSXP vector built from permanent CHARSXPs.
51///
52/// Each element is a `&CStr` literal routed through `Rf_install` + `PRINTNAME`
53/// for a never-GC'd CHARSXP. The STRSXP itself is kept alive via
54/// `R_PreserveObject`.
55///
56/// ```ignore
57/// // Single-element class:
58/// cached_strsxp!(pub(crate) fn date_class_sexp() = [c"Date"]);
59///
60/// // Multi-element class:
61/// cached_strsxp!(pub(crate) fn posixct_class_sexp() = [c"POSIXct", c"POSIXt"]);
62///
63/// // With feature gate:
64/// cached_strsxp!(
65///     #[cfg(any(feature = "time", feature = "arrow"))]
66///     pub(crate) fn posixct_class_sexp() = [c"POSIXct", c"POSIXt"]
67/// );
68/// ```
69macro_rules! cached_strsxp {
70    ($(#[$meta:meta])* $vis:vis fn $name:ident() = [$($cstr:expr),+ $(,)?]) => {
71        $(#[$meta])*
72        $vis fn $name() -> $crate::ffi::SEXP {
73            static CACHE: ::std::sync::OnceLock<$crate::ffi::SEXP> = ::std::sync::OnceLock::new();
74            *CACHE.get_or_init(|| unsafe {
75                use $crate::ffi::SexpExt as _;
76                let strings: &[&::std::ffi::CStr] = &[$($cstr),+];
77                let sexp = $crate::ffi::Rf_allocVector(
78                    $crate::ffi::SEXPTYPE::STRSXP,
79                    strings.len() as ::std::primitive::isize,
80                );
81                $crate::ffi::R_PreserveObject(sexp);
82                for (i, s) in strings.iter().enumerate() {
83                    sexp.set_string_elt(
84                        i as ::std::primitive::isize,
85                        $crate::cached_class::permanent_charsxp(s),
86                    );
87                }
88                sexp
89            })
90        }
91    };
92}
93#[allow(unused_imports)] // exported for use by other modules
94pub(crate) use cached_strsxp;
95
96// endregion
97
98// region: Permanent CHARSXP helper
99
100/// Get a permanent CHARSXP for a string by going through `Rf_install` + `PRINTNAME`.
101///
102/// Symbols are never GC'd, so the CHARSXP from `PRINTNAME` is valid forever.
103/// This avoids the `Rf_mkCharLenCE` hash lookup on repeated calls.
104///
105/// Used by [`cached_strsxp!`] — `pub(crate)` so the macro can reference it
106/// from any module.
107#[doc(hidden)]
108#[inline]
109pub(crate) fn permanent_charsxp(name: &std::ffi::CStr) -> crate::ffi::SEXP {
110    use crate::ffi::SexpExt;
111    unsafe { crate::ffi::Rf_install(name.as_ptr()) }.printname()
112}
113
114// endregion
115
116// region: Class vectors
117
118cached_strsxp!(
119    /// Cached `c("POSIXct", "POSIXt")` class STRSXP.
120    #[cfg(any(feature = "time", feature = "jiff", feature = "arrow"))]
121    pub(crate) fn posixct_class_sexp() = [c"POSIXct", c"POSIXt"]
122);
123
124cached_strsxp!(
125    /// Cached `"Date"` class STRSXP.
126    #[cfg(any(feature = "time", feature = "jiff", feature = "arrow"))]
127    pub(crate) fn date_class_sexp() = [c"Date"]
128);
129
130cached_strsxp!(
131    /// Cached `"data.frame"` class STRSXP.
132    pub(crate) fn data_frame_class_sexp() = [c"data.frame"]
133);
134
135cached_strsxp!(
136    /// Cached `"rust_condition_value"` class STRSXP — applied to every tagged
137    /// SEXP produced by `make_rust_condition_value` to identify panic-transport
138    /// values to the generated R wrappers.
139    pub(crate) fn rust_condition_class_sexp() = [c"rust_condition_value"]
140);
141
142cached_strsxp!(
143    /// Cached `c("error", "kind", "class", "call")` names STRSXP for condition values.
144    ///
145    /// Used by `make_rust_condition_value` which writes a 4-element list including
146    /// the optional user-supplied custom class.
147    pub(crate) fn condition_names_sexp() = [c"error", c"kind", c"class", c"call"]
148);
149
150// endregion
151
152// region: Scalar strings
153
154cached_strsxp!(
155    /// Cached `"UTC"` scalar string SEXP for the `tzone` attribute.
156    #[cfg(any(feature = "time", feature = "jiff"))]
157    fn utc_tzone_sexp() = [c"UTC"]
158);
159
160// endregion
161
162// region: Symbols
163
164cached_symbol!(
165    /// Cached `tzone` symbol.
166    #[cfg(any(feature = "time", feature = "jiff", feature = "arrow"))]
167    pub(crate) fn tzone_symbol() = c"tzone"
168);
169
170cached_symbol!(
171    /// Cached `__rust_condition__` symbol — the marker attribute on tagged
172    /// panic-transport SEXPs. Wrapper code asserts this is `TRUE` in addition
173    /// to the class check before re-raising via `.miniextendr_raise_condition`.
174    pub(crate) fn rust_condition_attr_symbol() = c"__rust_condition__"
175);
176
177cached_symbol!(
178    /// Cached `mx_raw_type` symbol (for raw conversion type tags).
179    #[cfg(feature = "raw_conversions")]
180    pub(crate) fn mx_raw_type_symbol() = c"mx_raw_type"
181);
182
183cached_symbol!(
184    /// Cached `ptype` symbol (vctrs list_of attribute).
185    #[cfg(feature = "vctrs")]
186    pub(crate) fn ptype_symbol() = c"ptype"
187);
188
189cached_symbol!(
190    /// Cached `size` symbol (vctrs list_of attribute).
191    #[cfg(feature = "vctrs")]
192    pub(crate) fn size_symbol() = c"size"
193);
194
195// endregion
196
197// region: Composite helpers
198
199/// Set class = `c("POSIXct", "POSIXt")` and tzone = `"UTC"` on an SEXP.
200///
201/// Uses cached class vector + tzone string — zero allocations after first call.
202///
203/// # Safety
204///
205/// `sexp` must be a valid REALSXP. Must be called on R's main thread.
206#[cfg(any(feature = "time", feature = "jiff"))]
207pub fn set_posixct_utc(sexp: crate::ffi::SEXP) {
208    use crate::ffi::SexpExt as _;
209    sexp.set_class(posixct_class_sexp());
210    sexp.set_attr(tzone_symbol(), utc_tzone_sexp());
211}
212
213/// Set class = `c("POSIXct", "POSIXt")` and tzone = `iana` on an SEXP.
214///
215/// Used by the jiff integration to round-trip `Zoned` timezone identity.
216/// Falls back to `"UTC"` for zones without an IANA name (e.g., fixed-offset zones).
217///
218/// # Safety
219///
220/// `sexp` must be a valid REALSXP. Must be called on R's main thread.
221#[cfg(feature = "jiff")]
222pub fn set_posixct_tz(sexp: crate::ffi::SEXP, iana: &str) {
223    use crate::ffi::SexpExt as _;
224    sexp.set_class(posixct_class_sexp());
225    // Build a one-element STRSXP for the tzone attribute.
226    unsafe {
227        let tzone_charsxp = crate::ffi::SEXP::charsxp(iana);
228        let tzone_sexp = crate::ffi::Rf_allocVector(crate::ffi::SEXPTYPE::STRSXP, 1);
229        crate::ffi::Rf_protect(tzone_sexp);
230        tzone_sexp.set_string_elt(0, tzone_charsxp);
231        sexp.set_attr(tzone_symbol(), tzone_sexp);
232        crate::ffi::Rf_unprotect(1);
233    }
234}
235
236// endregion
miniextendr_api/cached_class.rs

miniextendr_api/
cached_class.rs
