cxx/
unique_ptr.rs

1use crate::cxx_vector::{CxxVector, VectorElement};
2use crate::extern_type::ExternType;
3use crate::fmt::display;
4use crate::kind::Trivial;
5use crate::string::CxxString;
6#[cfg(feature = "std")]
7use alloc::string::String;
8#[cfg(feature = "std")]
9use alloc::vec::Vec;
10use core::cmp::Ordering;
11use core::ffi::c_void;
12use core::fmt::{self, Debug, Display};
13use core::hash::{Hash, Hasher};
14use core::marker::PhantomData;
15use core::mem::{self, MaybeUninit};
16use core::ops::{Deref, DerefMut};
17use core::pin::Pin;
18#[cfg(feature = "std")]
19use std::io::{self, IoSlice, Read, Seek, SeekFrom, Write};
20
21/// Binding to C++ `std::unique_ptr<T, std::default_delete<T>>`.
22#[repr(C)]
23pub struct UniquePtr<T>
24where
25    T: UniquePtrTarget,
26{
27    repr: MaybeUninit<*mut c_void>,
28    ty: PhantomData<T>,
29}
30
31impl<T> UniquePtr<T>
32where
33    T: UniquePtrTarget,
34{
35    /// Makes a new UniquePtr wrapping a null pointer.
36    ///
37    /// Matches the behavior of default-constructing a std::unique\_ptr.
38    pub fn null() -> Self {
39        UniquePtr {
40            repr: T::__null(),
41            ty: PhantomData,
42        }
43    }
44
45    /// Allocates memory on the heap and makes a UniquePtr pointing to it.
46    pub fn new(value: T) -> Self
47    where
48        T: ExternType<Kind = Trivial>,
49    {
50        UniquePtr {
51            repr: T::__new(value),
52            ty: PhantomData,
53        }
54    }
55
56    /// Checks whether the UniquePtr does not own an object.
57    ///
58    /// This is the opposite of [std::unique_ptr\<T\>::operator bool](https://en.cppreference.com/w/cpp/memory/unique_ptr/operator_bool).
59    pub fn is_null(&self) -> bool {
60        self.as_ptr().is_null()
61    }
62
63    /// Returns a reference to the object owned by this UniquePtr if any,
64    /// otherwise None.
65    pub fn as_ref(&self) -> Option<&T> {
66        let ptr = self.as_ptr();
67        unsafe { ptr.as_ref() }
68    }
69
70    /// Returns a mutable pinned reference to the object owned by this UniquePtr
71    /// if any, otherwise None.
72    pub fn as_mut(&mut self) -> Option<Pin<&mut T>> {
73        let ptr = self.as_mut_ptr();
74        unsafe {
75            let mut_reference = ptr.as_mut()?;
76            Some(Pin::new_unchecked(mut_reference))
77        }
78    }
79
80    /// Returns a mutable pinned reference to the object owned by this
81    /// UniquePtr.
82    ///
83    /// # Panics
84    ///
85    /// Panics if the UniquePtr holds a null pointer.
86    pub fn pin_mut(&mut self) -> Pin<&mut T> {
87        match self.as_mut() {
88            Some(target) => target,
89            None => panic!(
90                "called pin_mut on a null UniquePtr<{}>",
91                display(T::__typename),
92            ),
93        }
94    }
95
96    /// Returns a raw const pointer to the object owned by this UniquePtr if
97    /// any, otherwise the null pointer.
98    pub fn as_ptr(&self) -> *const T {
99        unsafe { T::__get(self.repr) }
100    }
101
102    /// Returns a raw mutable pointer to the object owned by this UniquePtr if
103    /// any, otherwise the null pointer.
104    ///
105    /// As with [std::unique_ptr\<T\>::get](https://en.cppreference.com/w/cpp/memory/unique_ptr/get),
106    /// this doesn't require that you hold an exclusive reference to the
107    /// UniquePtr. This differs from Rust norms, so extra care should be taken
108    /// in the way the pointer is used.
109    pub fn as_mut_ptr(&self) -> *mut T {
110        self.as_ptr() as *mut T
111    }
112
113    /// Consumes the UniquePtr, releasing its ownership of the heap-allocated T.
114    ///
115    /// Matches the behavior of [std::unique_ptr\<T\>::release](https://en.cppreference.com/w/cpp/memory/unique_ptr/release).
116    pub fn into_raw(self) -> *mut T {
117        let ptr = unsafe { T::__release(self.repr) };
118        mem::forget(self);
119        ptr
120    }
121
122    /// Constructs a UniquePtr retaking ownership of a pointer previously
123    /// obtained from `into_raw`.
124    ///
125    /// # Safety
126    ///
127    /// This function is unsafe because improper use may lead to memory
128    /// problems. For example a double-free may occur if the function is called
129    /// twice on the same raw pointer.
130    pub unsafe fn from_raw(raw: *mut T) -> Self {
131        UniquePtr {
132            repr: unsafe { T::__raw(raw) },
133            ty: PhantomData,
134        }
135    }
136}
137
138unsafe impl<T> Send for UniquePtr<T> where T: Send + UniquePtrTarget {}
139unsafe impl<T> Sync for UniquePtr<T> where T: Sync + UniquePtrTarget {}
140
141// UniquePtr is not a self-referential type and is safe to move out of a Pin,
142// regardless whether the pointer's target is Unpin.
143impl<T> Unpin for UniquePtr<T> where T: UniquePtrTarget {}
144
145impl<T> Drop for UniquePtr<T>
146where
147    T: UniquePtrTarget,
148{
149    fn drop(&mut self) {
150        unsafe { T::__drop(self.repr) }
151    }
152}
153
154impl<T> Deref for UniquePtr<T>
155where
156    T: UniquePtrTarget,
157{
158    type Target = T;
159
160    fn deref(&self) -> &Self::Target {
161        match self.as_ref() {
162            Some(target) => target,
163            None => panic!(
164                "called deref on a null UniquePtr<{}>",
165                display(T::__typename),
166            ),
167        }
168    }
169}
170
171impl<T> DerefMut for UniquePtr<T>
172where
173    T: UniquePtrTarget + Unpin,
174{
175    fn deref_mut(&mut self) -> &mut Self::Target {
176        match self.as_mut() {
177            Some(target) => Pin::into_inner(target),
178            None => panic!(
179                "called deref_mut on a null UniquePtr<{}>",
180                display(T::__typename),
181            ),
182        }
183    }
184}
185
186impl<T> Debug for UniquePtr<T>
187where
188    T: Debug + UniquePtrTarget,
189{
190    fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
191        match self.as_ref() {
192            None => formatter.write_str("nullptr"),
193            Some(value) => Debug::fmt(value, formatter),
194        }
195    }
196}
197
198impl<T> Display for UniquePtr<T>
199where
200    T: Display + UniquePtrTarget,
201{
202    fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
203        match self.as_ref() {
204            None => formatter.write_str("nullptr"),
205            Some(value) => Display::fmt(value, formatter),
206        }
207    }
208}
209
210impl<T> PartialEq for UniquePtr<T>
211where
212    T: PartialEq + UniquePtrTarget,
213{
214    fn eq(&self, other: &Self) -> bool {
215        self.as_ref() == other.as_ref()
216    }
217}
218
219impl<T> Eq for UniquePtr<T> where T: Eq + UniquePtrTarget {}
220
221impl<T> PartialOrd for UniquePtr<T>
222where
223    T: PartialOrd + UniquePtrTarget,
224{
225    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
226        PartialOrd::partial_cmp(&self.as_ref(), &other.as_ref())
227    }
228}
229
230impl<T> Ord for UniquePtr<T>
231where
232    T: Ord + UniquePtrTarget,
233{
234    fn cmp(&self, other: &Self) -> Ordering {
235        Ord::cmp(&self.as_ref(), &other.as_ref())
236    }
237}
238
239impl<T> Hash for UniquePtr<T>
240where
241    T: Hash + UniquePtrTarget,
242{
243    fn hash<H>(&self, hasher: &mut H)
244    where
245        H: Hasher,
246    {
247        self.as_ref().hash(hasher);
248    }
249}
250
251/// Forwarding `Read` trait implementation in a manner similar to `Box<T>`.
252///
253/// Note that the implementation will panic for null `UniquePtr<T>`.
254#[cfg(feature = "std")]
255impl<T> Read for UniquePtr<T>
256where
257    for<'a> Pin<&'a mut T>: Read,
258    T: UniquePtrTarget,
259{
260    #[inline]
261    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
262        self.pin_mut().read(buf)
263    }
264
265    #[inline]
266    fn read_to_end(&mut self, buf: &mut Vec<u8>) -> io::Result<usize> {
267        self.pin_mut().read_to_end(buf)
268    }
269
270    #[inline]
271    fn read_to_string(&mut self, buf: &mut String) -> io::Result<usize> {
272        self.pin_mut().read_to_string(buf)
273    }
274
275    #[inline]
276    fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
277        self.pin_mut().read_exact(buf)
278    }
279
280    // TODO: Foward other `Read` trait methods when they get stabilized (e.g.
281    // `read_buf` and/or `is_read_vectored`).
282}
283
284/// Forwarding `Seek` trait implementation in a manner similar to `Box<T>`.
285///
286/// Note that the implementation will panic for null `UniquePtr<T>`.
287#[cfg(feature = "std")]
288impl<T> Seek for UniquePtr<T>
289where
290    for<'a> Pin<&'a mut T>: Seek,
291    T: UniquePtrTarget,
292{
293    #[inline]
294    fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
295        self.pin_mut().seek(pos)
296    }
297
298    #[inline]
299    fn rewind(&mut self) -> io::Result<()> {
300        self.pin_mut().rewind()
301    }
302
303    #[inline]
304    fn stream_position(&mut self) -> io::Result<u64> {
305        self.pin_mut().stream_position()
306    }
307
308    #[inline]
309    fn seek_relative(&mut self, offset: i64) -> io::Result<()> {
310        self.pin_mut().seek_relative(offset)
311    }
312
313    // TODO: Foward other `Seek` trait methods if/when possible:
314    // * `stream_len`: If/when stabilized
315}
316
317/// Forwarding `Write` trait implementation in a manner similar to `Box<T>`.
318///
319/// Note that the implementation will panic for null `UniquePtr<T>`.
320#[cfg(feature = "std")]
321impl<T> Write for UniquePtr<T>
322where
323    for<'a> Pin<&'a mut T>: Write,
324    T: UniquePtrTarget,
325{
326    #[inline]
327    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
328        self.pin_mut().write(buf)
329    }
330
331    #[inline]
332    fn write_vectored(&mut self, bufs: &[IoSlice]) -> io::Result<usize> {
333        self.pin_mut().write_vectored(bufs)
334    }
335
336    #[inline]
337    fn flush(&mut self) -> io::Result<()> {
338        self.pin_mut().flush()
339    }
340
341    #[inline]
342    fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
343        self.pin_mut().write_all(buf)
344    }
345
346    #[inline]
347    fn write_fmt(&mut self, fmt: fmt::Arguments) -> io::Result<()> {
348        self.pin_mut().write_fmt(fmt)
349    }
350
351    // TODO: Foward other `Write` trait methods when they get stabilized (e.g.
352    // `write_all_vectored` and/or `is_write_vectored`).
353}
354
355/// Trait bound for types which may be used as the `T` inside of a
356/// `UniquePtr<T>` in generic code.
357///
358/// This trait has no publicly callable or implementable methods. Implementing
359/// it outside of the CXX codebase is not supported.
360///
361/// # Example
362///
363/// A bound `T: UniquePtrTarget` may be necessary when manipulating
364/// [`UniquePtr`] in generic code.
365///
366/// ```
367/// use cxx::memory::{UniquePtr, UniquePtrTarget};
368/// use std::fmt::Display;
369///
370/// pub fn take_generic_ptr<T>(ptr: UniquePtr<T>)
371/// where
372///     T: UniquePtrTarget + Display,
373/// {
374///     println!("the unique_ptr points to: {}", *ptr);
375/// }
376/// ```
377///
378/// Writing the same generic function without a `UniquePtrTarget` trait bound
379/// would not compile.
380pub unsafe trait UniquePtrTarget {
381    #[doc(hidden)]
382    fn __typename(f: &mut fmt::Formatter) -> fmt::Result;
383    #[doc(hidden)]
384    fn __null() -> MaybeUninit<*mut c_void>;
385    #[doc(hidden)]
386    fn __new(value: Self) -> MaybeUninit<*mut c_void>
387    where
388        Self: Sized,
389    {
390        // Opaque C types do not get this method because they can never exist by
391        // value on the Rust side of the bridge.
392        let _ = value;
393        unreachable!()
394    }
395    #[doc(hidden)]
396    unsafe fn __raw(raw: *mut Self) -> MaybeUninit<*mut c_void>;
397    #[doc(hidden)]
398    unsafe fn __get(repr: MaybeUninit<*mut c_void>) -> *const Self;
399    #[doc(hidden)]
400    unsafe fn __release(repr: MaybeUninit<*mut c_void>) -> *mut Self;
401    #[doc(hidden)]
402    unsafe fn __drop(repr: MaybeUninit<*mut c_void>);
403}
404
405extern "C" {
406    #[link_name = "cxxbridge1$unique_ptr$std$string$null"]
407    fn unique_ptr_std_string_null(this: *mut MaybeUninit<*mut c_void>);
408    #[link_name = "cxxbridge1$unique_ptr$std$string$raw"]
409    fn unique_ptr_std_string_raw(this: *mut MaybeUninit<*mut c_void>, raw: *mut CxxString);
410    #[link_name = "cxxbridge1$unique_ptr$std$string$get"]
411    fn unique_ptr_std_string_get(this: *const MaybeUninit<*mut c_void>) -> *const CxxString;
412    #[link_name = "cxxbridge1$unique_ptr$std$string$release"]
413    fn unique_ptr_std_string_release(this: *mut MaybeUninit<*mut c_void>) -> *mut CxxString;
414    #[link_name = "cxxbridge1$unique_ptr$std$string$drop"]
415    fn unique_ptr_std_string_drop(this: *mut MaybeUninit<*mut c_void>);
416}
417
418unsafe impl UniquePtrTarget for CxxString {
419    fn __typename(f: &mut fmt::Formatter) -> fmt::Result {
420        f.write_str("CxxString")
421    }
422    fn __null() -> MaybeUninit<*mut c_void> {
423        let mut repr = MaybeUninit::uninit();
424        unsafe {
425            unique_ptr_std_string_null(&mut repr);
426        }
427        repr
428    }
429    unsafe fn __raw(raw: *mut Self) -> MaybeUninit<*mut c_void> {
430        let mut repr = MaybeUninit::uninit();
431        unsafe { unique_ptr_std_string_raw(&mut repr, raw) }
432        repr
433    }
434    unsafe fn __get(repr: MaybeUninit<*mut c_void>) -> *const Self {
435        unsafe { unique_ptr_std_string_get(&repr) }
436    }
437    unsafe fn __release(mut repr: MaybeUninit<*mut c_void>) -> *mut Self {
438        unsafe { unique_ptr_std_string_release(&mut repr) }
439    }
440    unsafe fn __drop(mut repr: MaybeUninit<*mut c_void>) {
441        unsafe { unique_ptr_std_string_drop(&mut repr) }
442    }
443}
444
445unsafe impl<T> UniquePtrTarget for CxxVector<T>
446where
447    T: VectorElement,
448{
449    fn __typename(f: &mut fmt::Formatter) -> fmt::Result {
450        write!(f, "CxxVector<{}>", display(T::__typename))
451    }
452    fn __null() -> MaybeUninit<*mut c_void> {
453        T::__unique_ptr_null()
454    }
455    unsafe fn __raw(raw: *mut Self) -> MaybeUninit<*mut c_void> {
456        unsafe { T::__unique_ptr_raw(raw) }
457    }
458    unsafe fn __get(repr: MaybeUninit<*mut c_void>) -> *const Self {
459        unsafe { T::__unique_ptr_get(repr) }
460    }
461    unsafe fn __release(repr: MaybeUninit<*mut c_void>) -> *mut Self {
462        unsafe { T::__unique_ptr_release(repr) }
463    }
464    unsafe fn __drop(repr: MaybeUninit<*mut c_void>) {
465        unsafe { T::__unique_ptr_drop(repr) }
466    }
467}
cxx/unique_ptr.rs

cxx/
unique_ptr.rs
