fbl/
ref_ptr.rs

1// Copyright 2026 The Fuchsia Authors
2//
3// Use of this source code is governed by a MIT-style
4// license that can be found in the LICENSE file or at
5// https://opensource.org/licenses/MIT
6
7use crate::recyclable::{Recyclable, UninitRecyclable};
8use crate::ref_counted::HasRefCount;
9use core::mem::MaybeUninit;
10use core::ops::Deref;
11use core::ptr::NonNull;
12use kalloc::AllocError;
13
14use pin_init::{Init, PinInit};
15
16/// `RefPtr<T>` holds a reference to an intrusively-refcounted object of type
17/// T that deletes the object when the refcount drops to 0.
18///
19/// T should be a struct that contains a `fbl::RefCounted` field and implements
20/// `HasRefCount` and `Destroy` traits.
21#[repr(C)]
22pub struct RefPtr<T>
23where
24    T: HasRefCount + Recyclable,
25{
26    ptr: NonNull<T>,
27}
28
29impl<T: HasRefCount + Recyclable> RefPtr<T> {
30    /// Constructs a `RefPtr` from a raw pointer that has already been adopted.
31    ///
32    /// # Safety
33    ///
34    /// - The caller must ensure that `ptr` is valid and has a ref count already
35    ///   acquired.
36    /// - `ptr` must have been allocated in such a way that calling `T::recycle(ptr)` is a
37    ///   correct way to deallocate the pointer.
38    pub unsafe fn from_raw(ptr: *const T) -> Self {
39        // SAFETY: The caller must ensure that ptr is valid.
40        unsafe { RefPtr { ptr: NonNull::new_unchecked(ptr as *mut T) } }
41    }
42
43    /// Constructs a `RefPtr` from a raw pointer that has already been adopted, unless the pointer
44    /// is null.
45    ///
46    /// # Safety
47    ///
48    /// The caller must ensure that `ptr` is either null or, if not null that:
49    /// - a ref count already acquired.
50    /// - has been allocated in such a way that calling `T::recycle(ptr)` is a correct way to
51    ///   deallocate the pointer.
52    pub unsafe fn try_from_raw(ptr: *const T) -> Option<Self> {
53        NonNull::new(ptr as *mut T).map(|ptr| RefPtr { ptr })
54    }
55
56    /// Helper function that allocates a new instance of `T` using `T::allocate` and
57    /// returns a `RefPtr` wrapping it.
58    ///
59    /// This is an internal helper function that should not be used directly.
60    /// Use the `make_ref_counted!(...)` macro instead of this function to properly
61    /// initialize the ref count.
62    ///
63    /// # Safety
64    ///
65    /// The caller must ensure that `T` has a RefCounted field that is not
66    /// already adopted.
67    pub unsafe fn try_new(value: T) -> Result<RefPtr<T>, AllocError> {
68        let mut ptr = T::allocate(value)?;
69        // SAFETY: The caller must ensure that T has a RefCounted field that is not
70        // already adopted.
71        unsafe { ptr.as_mut().ref_count().adopt() };
72        Ok(RefPtr { ptr })
73    }
74
75    /// Returns the raw pointer to the object.
76    pub fn as_ptr(this: &Self) -> *const T {
77        this.ptr.as_ptr()
78    }
79
80    /// Returns `true` if the two `RefPtr`s point to the same object.
81    pub fn ptr_eq(a: &Self, b: &Self) -> bool {
82        a.ptr == b.ptr
83    }
84
85    /// Consume the `RefPtr` and return the raw pointer without modifying the ref count.
86    ///
87    /// The caller is responsible for maintaining the reference count.
88    pub fn into_raw(this: Self) -> *const T {
89        let ptr = this.ptr;
90        core::mem::forget(this);
91        ptr.as_ptr()
92    }
93
94    /// Casts this `RefPtr` to point to a different type.
95    ///
96    /// # Safety
97    ///
98    /// The caller must ensure that the object pointed to by this `RefPtr` can be safely
99    /// treated as an instance of type `U`.
100    pub unsafe fn cast<U>(self) -> RefPtr<U>
101    where
102        U: HasRefCount + Recyclable,
103    {
104        let ptr = self.ptr.cast::<U>();
105        core::mem::forget(self);
106        RefPtr { ptr }
107    }
108
109    /// Use the given pin-initializer to pin-initialize a `T` inside of a new `RefPtr`.
110    pub fn try_pin_init<E>(init: impl PinInit<T, E>) -> Result<Self, E>
111    where
112        T: UninitRecyclable,
113        E: From<AllocError>,
114    {
115        let ptr = T::allocate_uninit()?;
116        let guard = UninitRefGuard { ptr };
117        let slot = guard.ptr.as_ptr() as *mut T;
118        // SAFETY: `slot` is valid and will not be moved.
119        unsafe { init.__pinned_init(slot)? };
120        // SAFETY: The object is now initialized, so we can access its ref_count.
121        unsafe { (*slot).ref_count().adopt() };
122        let initialized_ptr = guard.ptr.cast::<T>();
123        core::mem::forget(guard);
124        let initialized_ref = RefPtr { ptr: initialized_ptr };
125        Ok(initialized_ref)
126    }
127
128    /// Use the given initializer to in-place initialize a `T` inside of a new `RefPtr`.
129    pub fn try_init<E>(init: impl Init<T, E>) -> Result<Self, E>
130    where
131        T: UninitRecyclable,
132        E: From<AllocError>,
133    {
134        let ptr = T::allocate_uninit()?;
135        let guard = UninitRefGuard { ptr };
136        let slot = guard.ptr.as_ptr() as *mut T;
137        // SAFETY: `slot` is valid.
138        unsafe { init.__init(slot)? };
139        // SAFETY: The object is now initialized, so we can access its ref_count.
140        unsafe { (*slot).ref_count().adopt() };
141        let initialized_ptr = guard.ptr.cast::<T>();
142        core::mem::forget(guard);
143        Ok(RefPtr { ptr: initialized_ptr })
144    }
145
146    /// Use the given pin-initializer to pin-initialize a `T` inside of a new `RefPtr`.
147    #[inline]
148    pub fn pin_init(init: impl PinInit<T, core::convert::Infallible>) -> Result<Self, AllocError>
149    where
150        T: UninitRecyclable,
151    {
152        let init = unsafe {
153            ::pin_init::pin_init_from_closure(|slot| {
154                init.__pinned_init(slot).map_err(|i| match i {})
155            })
156        };
157        Self::try_pin_init(init)
158    }
159
160    /// Use the given initializer to in-place initialize a `T` inside of a new `RefPtr`.
161    #[inline]
162    pub fn init(init: impl Init<T, core::convert::Infallible>) -> Result<Self, AllocError>
163    where
164        T: UninitRecyclable,
165    {
166        let init = unsafe {
167            ::pin_init::init_from_closure(|slot| init.__init(slot).map_err(|i| match i {}))
168        };
169        Self::try_init(init)
170    }
171}
172
173impl<T: HasRefCount + Recyclable> Deref for RefPtr<T> {
174    type Target = T;
175    fn deref(&self) -> &Self::Target {
176        unsafe { self.ptr.as_ref() }
177    }
178}
179
180impl<T: HasRefCount + Recyclable> Clone for RefPtr<T> {
181    fn clone(&self) -> Self {
182        self.deref().ref_count().add_ref();
183        RefPtr { ptr: self.ptr }
184    }
185}
186
187impl<T: HasRefCount + Recyclable> Drop for RefPtr<T> {
188    fn drop(&mut self) {
189        if self.deref().ref_count().release() {
190            unsafe {
191                T::recycle(self.ptr);
192            }
193        }
194    }
195}
196
197impl<T: HasRefCount + Recyclable> PartialEq for RefPtr<T> {
198    fn eq(&self, other: &Self) -> bool {
199        RefPtr::ptr_eq(self, other)
200    }
201}
202
203impl<T: HasRefCount + Recyclable> Eq for RefPtr<T> {}
204
205unsafe impl<T: HasRefCount + Recyclable + Send + Sync> Send for RefPtr<T> {}
206unsafe impl<T: HasRefCount + Recyclable + Send + Sync> Sync for RefPtr<T> {}
207
208struct UninitRefGuard<T: UninitRecyclable> {
209    ptr: NonNull<MaybeUninit<T>>,
210}
211
212impl<T: UninitRecyclable> Drop for UninitRefGuard<T> {
213    fn drop(&mut self) {
214        unsafe {
215            T::recycle_uninit(self.ptr);
216        }
217    }
218}
219
220/// Macro to construct a RefPtr, automatically populating the ref_count field.
221#[macro_export]
222macro_rules! make_ref_counted {
223    ($ty:ident { $($field:ident : $val:expr),* $(,)? }) => {
224        // SAFETY: The macro creates a new object with a ref count of 1.
225        unsafe {
226            $crate::RefPtr::try_new($ty {
227                ref_count: $crate::RefCounted::new(),
228                __fbl_ref_counted_guard: (),
229                $($field : $val),*
230            })
231        }
232    };
233}
234
235/// Macro to construct a RefPtr with pin-initialization, automatically populating the ref_count
236/// field.
237#[macro_export]
238macro_rules! pin_make_ref_counted {
239    ($ty:ident { $($field:tt)* }) => {
240        $crate::RefPtr::pin_init($crate::pin_init::pin_init!($ty {
241            ref_count: $crate::RefCounted::new(),
242            __fbl_ref_counted_guard: (),
243            $($field)*
244        }))
245    };
246}
247
248/// Macro to construct a RefPtr with fallible pin-initialization, automatically populating the
249/// ref_count field.
250#[macro_export]
251macro_rules! try_pin_make_ref_counted {
252    ($ty:ident { $($field:tt)* }) => {
253        $crate::RefPtr::try_pin_init($crate::pin_init::pin_init!($ty {
254            ref_count: $crate::RefCounted::new(),
255            __fbl_ref_counted_guard: (),
256            $($field)*
257        }))
258    };
259}
260
261#[cfg(test)]
262mod tests {
263    use super::*;
264    use core::ffi::c_void;
265    use core::pin::Pin;
266    use core::ptr::null;
267    use core::sync::atomic::{AtomicBool, Ordering};
268
269    extern crate alloc;
270    use alloc::sync::Arc;
271
272    #[unsafe(no_mangle)]
273    pub extern "C" fn rust_recycle_test_rust_ref_counted(ptr: *mut c_void) {
274        unsafe { TestRustRefCounted::recycle_ffi(ptr) }
275    }
276
277    unsafe extern "C" {
278        fn test_import_rust_ref_counted(ptr: *mut c_void);
279    }
280
281    #[fbl::ref_counted]
282    #[pin_init::pin_data(PinnedDrop)]
283    #[derive(crate::Recyclable)]
284    #[repr(C)]
285    pub struct TestRustRefCounted {
286        destroyed: Arc<AtomicBool>,
287    }
288
289    ::zr::static_assert!(core::mem::size_of::<RefPtr<TestRustRefCounted>>() == 8);
290    ::zr::static_assert!(core::mem::align_of::<RefPtr<TestRustRefCounted>>() == 8);
291    ::zr::static_assert!(core::mem::size_of::<Option<RefPtr<TestRustRefCounted>>>() == 8);
292    ::zr::static_assert!(core::mem::align_of::<Option<RefPtr<TestRustRefCounted>>>() == 8);
293
294    #[pin_init::pinned_drop]
295    impl pin_init::PinnedDrop for TestRustRefCounted {
296        fn drop(self: Pin<&mut Self>) {
297            self.destroyed.store(true, Ordering::Relaxed);
298        }
299    }
300
301    #[test]
302    fn test_rust_drops_reference() {
303        let destroyed = Arc::new(AtomicBool::new(false));
304        {
305            let ref_ptr =
306                make_ref_counted!(TestRustRefCounted { destroyed: destroyed.clone() }).unwrap();
307            assert!(!destroyed.load(Ordering::Relaxed));
308            let ref_ptr_clone = ref_ptr.clone();
309            drop(ref_ptr_clone);
310            assert!(!destroyed.load(Ordering::Relaxed));
311        } // Drop ref_ptr -> count becomes 0 -> calls destroy -> triggers Drop trait!
312
313        assert!(destroyed.load(Ordering::Relaxed));
314    }
315
316    #[test]
317    #[cfg_attr(miri, ignore = "miri does not support calling foreign functions")]
318    fn test_cpp_drops_reference() {
319        let destroyed = Arc::new(AtomicBool::new(false));
320        let ref_ptr =
321            make_ref_counted!(TestRustRefCounted { destroyed: destroyed.clone() }).unwrap();
322        let raw_ptr = RefPtr::into_raw(ref_ptr);
323
324        unsafe {
325            assert!(!destroyed.load(Ordering::Relaxed));
326            // Pass to C++!
327            test_import_rust_ref_counted(raw_ptr as *const TestRustRefCounted as *mut c_void);
328            // C++ should have acquired reference and released it!
329            // And since count was 1, it should have dropped it!
330            assert!(destroyed.load(Ordering::Relaxed));
331        }
332    }
333
334    #[test]
335    fn test_ref_ptr_compare() {
336        let destroyed1 = Arc::new(AtomicBool::new(false));
337        let destroyed2 = Arc::new(AtomicBool::new(false));
338        let ptr1 = make_ref_counted!(TestRustRefCounted { destroyed: destroyed1.clone() }).unwrap();
339        let ptr2 = make_ref_counted!(TestRustRefCounted { destroyed: destroyed2.clone() }).unwrap();
340        let ptr1_clone = ptr1.clone();
341
342        assert!(ptr1 == ptr1);
343        assert!(ptr1 != ptr2);
344        assert!(ptr1 == ptr1_clone);
345    }
346
347    #[test]
348    fn test_rust_pin_init() {
349        let destroyed = Arc::new(AtomicBool::new(false));
350        let destroyed_clone = destroyed.clone();
351        {
352            let ref_ptr =
353                pin_make_ref_counted!(TestRustRefCounted { destroyed: destroyed_clone }).unwrap();
354            assert!(!destroyed.load(Ordering::Relaxed));
355            let ref_ptr_clone = ref_ptr.clone();
356            drop(ref_ptr_clone);
357            assert!(!destroyed.load(Ordering::Relaxed));
358        } // Drop ref_ptr
359        assert!(destroyed.load(Ordering::Relaxed));
360    }
361
362    #[fbl::ref_counted]
363    #[pin_init::pin_data]
364    #[derive(crate::Recyclable)]
365    #[repr(C)]
366    struct FallibleInit {
367        value: i32,
368    }
369
370    #[test]
371    fn test_rust_try_pin_init_fail() {
372        let init = unsafe {
373            ::pin_init::pin_init_from_closure(
374                |_slot: *mut FallibleInit| -> Result<(), AllocError> { Err(AllocError) },
375            )
376        };
377        let res = RefPtr::try_pin_init(init);
378        assert!(res.is_err());
379    }
380
381    #[test]
382    fn test_null_try_from() {
383        let maybe_ref_ptr = unsafe { RefPtr::try_from_raw(null::<TestRustRefCounted>()) };
384        assert!(maybe_ref_ptr.is_none());
385    }
386}
fbl/ref_ptr.rs

fbl/
ref_ptr.rs
