1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
//! `ExternalPtr` is a way to leak Rust allocated data to R, forego deallocation
//! to R and its GC strategy.
//!
//! An `ExternalPtr` encompasses three values, an owned pointer to the Rust
//! type, a `tag` and a `prot`. Tag is a helpful naming of the type, but
//! it doesn't offer any solid type-checking capability. And `prot` is meant
//! to be R values, that are supposed to be kept together with the `ExternalPtr`.
//!
//! Neither `tag` nor `prot` are attributes, therefore to use `ExternalPtr` as
//! a class in R, you must decorate it with a class-attribute manually.
//!
//! **Beware**: Equality (by way of `PartialEq`) does not imply equality of value,
//! but equality of pointer. Two objects stored as `ExternalPtr` may be equal
//! in value, but be two distinct entities, with distinct pointers.
//!
//! Instead, rely on `AsRef` to make _by value_ comparison, e.g. to compare
//! for equality of
//! two instances of `ExternalPtr<T>` by value, `a.as_ref() == b.as_ref()`.
//!
use super::*;
use std::fmt::Debug;

/// Wrapper for creating R objects containing any Rust object.
///
/// ```
/// use extendr_api::prelude::*;
/// test! {
///     let extptr = ExternalPtr::new(1);
///     assert_eq!(*extptr, 1);
///     let robj : Robj = extptr.into();
///     let extptr2 : ExternalPtr<i32> = robj.try_into().unwrap();
///     assert_eq!(*extptr2, 1);
/// }
/// ```
#[repr(transparent)]
pub struct ExternalPtr<T> {
    /// This is the contained Robj.
    pub(crate) robj: Robj,

    /// This is a zero-length object that holds the type of the object.
    _marker: std::marker::PhantomData<T>,
}

/// Manual implementation of `PartialEq`, because the constraint `T: PartialEq`
/// is not necessary.
impl<T> PartialEq for ExternalPtr<T> {
    fn eq(&self, other: &Self) -> bool {
        self.robj == other.robj && self._marker == other._marker
    }
}

/// Manual implementation of `Clone` trait, because the assumed constraint `T: Clone` is not necessary.
impl<T> Clone for ExternalPtr<T> {
    fn clone(&self) -> Self {
        Self {
            robj: self.robj.clone(),
            _marker: self._marker,
        }
    }
}

impl<T> robj::GetSexp for ExternalPtr<T> {
    unsafe fn get(&self) -> SEXP {
        self.robj.get()
    }

    unsafe fn get_mut(&mut self) -> SEXP {
        self.robj.get_mut()
    }

    /// Get a reference to a Robj for this type.
    fn as_robj(&self) -> &Robj {
        &self.robj
    }

    /// Get a mutable reference to a Robj for this type.
    fn as_robj_mut(&mut self) -> &mut Robj {
        &mut self.robj
    }
}

/// len() and is_empty()
impl<T> Length for ExternalPtr<T> {}

/// rtype() and rany()
impl<T> Types for ExternalPtr<T> {}

/// `set_attrib`
impl<T> Attributes for ExternalPtr<T> {}

/// as_*()
impl<T> Conversions for ExternalPtr<T> {}

/// find_var() etc.
impl<T> Rinternals for ExternalPtr<T> {}

/// as_typed_slice_raw() etc.
impl<T> Slices for ExternalPtr<T> {}

/// dollar() etc.
impl<T> Operators for ExternalPtr<T> {}

impl<T> Deref for ExternalPtr<T> {
    type Target = T;

    /// This allows us to treat the Robj as if it is the type T.
    fn deref(&self) -> &Self::Target {
        self.addr()
    }
}

impl<T> DerefMut for ExternalPtr<T> {
    /// This allows us to treat the Robj as if it is the mutable type T.
    fn deref_mut(&mut self) -> &mut Self::Target {
        self.addr_mut()
    }
}

impl<T> ExternalPtr<T> {
    /// Construct an external pointer object from any type T.
    /// In this case, the R object owns the data and will drop the Rust object
    /// when the last reference is removed via register_c_finalizer.
    ///
    /// An ExternalPtr behaves like a Box except that the information is
    /// tracked by a R object.
    pub fn new(val: T) -> Self {
        single_threaded(|| unsafe {
            // This allocates some memory for our object and moves the object into it.
            let boxed = Box::new(val);

            // This constructs an external pointer to our boxed data.
            // into_raw() converts the box to a malloced pointer.
            let robj = Robj::make_external_ptr(Box::into_raw(boxed), r!(()));

            extern "C" fn finalizer<T>(x: SEXP) {
                unsafe {
                    let ptr = R_ExternalPtrAddr(x).cast::<T>();

                    // Free the `tag`, which is the type-name
                    R_SetExternalPtrTag(x, R_NilValue);

                    // Convert the pointer to a box and drop it implictly.
                    // This frees up the memory we have used and calls the "T::drop" method if there is one.
                    drop(Box::from_raw(ptr));

                    // Now set the pointer in ExternalPTR to C `NULL`
                    R_ClearExternalPtr(x);
                }
            }

            // Tell R about our finalizer
            robj.register_c_finalizer(Some(finalizer::<T>));

            // Return an object in a wrapper.
            Self {
                robj,
                _marker: std::marker::PhantomData,
            }
        })
    }

    // TODO: make a constructor for references?

    /// Get the "tag" of an external pointer. This is the type name in the common case.
    pub fn tag(&self) -> Robj {
        unsafe { Robj::from_sexp(R_ExternalPtrTag(self.robj.get())) }
    }

    /// Get the "protected" field of an external pointer. This is NULL in the common case.
    pub fn protected(&self) -> Robj {
        unsafe { Robj::from_sexp(R_ExternalPtrProtected(self.robj.get())) }
    }

    /// Get the "address" field of an external pointer.
    /// Normally, we will use Deref to do this.
    ///
    /// ## Panics
    ///
    /// When the underlying pointer is C `NULL`.
    pub fn addr(&self) -> &T {
        self.try_addr().unwrap()
    }

    /// Get the "address" field of an external pointer as a mutable reference.
    /// Normally, we will use DerefMut to do this.
    ///
    /// ## Panics
    ///
    /// When the underlying pointer is C `NULL`.
    pub fn addr_mut(&mut self) -> &mut T {
        self.try_addr_mut().unwrap()
    }
    /// Get the "address" field of an external pointer.
    /// Normally, we will use Deref to do this.
    ///
    /// ## Panics
    ///
    /// When the underlying pointer is C `NULL`.
    pub fn try_addr(&self) -> Result<&T> {
        unsafe {
            R_ExternalPtrAddr(self.robj.get())
                .cast::<T>()
                .cast_const()
                .as_ref()
                .ok_or_else(|| Error::ExpectedExternalNonNullPtr(self.robj.clone()))
        }
    }

    /// Get the "address" field of an external pointer as a mutable reference.
    /// Normally, we will use DerefMut to do this.
    ///
    /// ## Panics
    ///
    /// When the underlying pointer is C `NULL`.
    pub fn try_addr_mut(&mut self) -> Result<&mut T> {
        unsafe {
            R_ExternalPtrAddr(self.robj.get_mut())
                .cast::<T>()
                .as_mut()
                .ok_or_else(|| Error::ExpectedExternalNonNullPtr(self.robj.clone()))
        }
    }
}

impl<T> TryFrom<&Robj> for &ExternalPtr<T> {
    type Error = Error;

    fn try_from(value: &Robj) -> Result<Self> {
        if !value.is_external_pointer() {
            return Err(Error::ExpectedExternalPtr(value.clone()));
        }
        unsafe { Ok(std::mem::transmute(value)) }
    }
}

impl<T> TryFrom<&mut Robj> for &mut ExternalPtr<T> {
    type Error = Error;

    fn try_from(value: &mut Robj) -> Result<Self> {
        if !value.is_external_pointer() {
            return Err(Error::ExpectedExternalPtr(value.clone()));
        }
        unsafe { Ok(std::mem::transmute(value)) }
    }
}

impl<T> TryFrom<&Robj> for ExternalPtr<T> {
    type Error = Error;

    fn try_from(robj: &Robj) -> Result<Self> {
        let result: &Self = robj.try_into()?;
        Ok(result.clone())
    }
}

impl<T> TryFrom<Robj> for ExternalPtr<T> {
    type Error = Error;

    fn try_from(robj: Robj) -> Result<Self> {
        <ExternalPtr<T>>::try_from(&robj)
    }
}

impl<T> From<ExternalPtr<T>> for Robj {
    fn from(val: ExternalPtr<T>) -> Self {
        val.robj
    }
}

impl<T: Debug> std::fmt::Debug for ExternalPtr<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        (&**self as &T).fmt(f)
    }
}

impl<T> AsRef<T> for ExternalPtr<T> {
    fn as_ref(&self) -> &T {
        self.addr()
    }
}

impl<T> AsMut<T> for ExternalPtr<T> {
    fn as_mut(&mut self) -> &mut T {
        self.addr_mut()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use extendr_engine::with_r;

    #[derive(Debug)]
    struct BareWrapper(i32);

    #[test]
    fn externalptr_is_ptr() {
        with_r(|| {
            let a = BareWrapper(42);
            let b = BareWrapper(42);
            assert_eq!(a.0, b.0);

            let a_ptr = std::ptr::addr_of!(a);
            let b_ptr = std::ptr::addr_of!(b);
            let a_externalptr = ExternalPtr::new(a);
            let b_externalptr = ExternalPtr::new(b);

            assert_ne!(
                a_ptr, b_ptr,
                "pointers has to be equal by address, not value"
            );

            assert_ne!(
                a_externalptr.robj, b_externalptr.robj,
                "R only knows about the pointer, and not the pointee"
            );
            assert_ne!(
                a_externalptr, b_externalptr,
                "ExternalPtr acts exactly like a pointer"
            );
            assert_ne!(&a_externalptr, &b_externalptr,);
        });
    }

    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)]
    struct Wrapper(i32);

    #[test]
    fn compare_externalptr_pointee() {
        with_r(|| {
            let a = Wrapper(42);
            let b = Wrapper(42);
            let a_externalptr = ExternalPtr::new(a);
            let b_externalptr = ExternalPtr::new(b);
            assert_eq!(a_externalptr.as_ref(), b_externalptr.as_ref());

            // let's test more use of `PartialOrd` on `T`
            let a_externalptr = ExternalPtr::new(Wrapper(50));
            let b_externalptr = ExternalPtr::new(Wrapper(60));
            assert!(a_externalptr.as_ref() <= b_externalptr.as_ref());
            assert_eq!(
                a_externalptr.as_ref().max(b_externalptr.as_ref()),
                &Wrapper(60)
            )
        });
    }
}