1 // SPDX-License-Identifier: GPL-2.0
3 //! A reference-counted pointer.
5 //! This module implements a way for users to create reference-counted objects and pointers to
6 //! them. Such a pointer automatically increments and decrements the count, and drops the
13 //! 3. It saturates the reference count instead of aborting when it goes over a threshold.
17 //! [`Arc`]: https://doc.rust-lang.org/std/sync/struct.Arc.html
32     pin::Pin,
39 /// A reference-counted pointer to an instance of `T`.
41 /// The reference count is incremented when new instances of [`Arc`] are created, and decremented
42 /// when they are dropped. When the count reaches zero, the underlying `T` is also dropped.
46 /// The reference count on an instance of [`Arc`] is always non-zero.
135     // meaningful with respect to dropck - but this may change in the future so this is left here
138     // See https://doc.rust-lang.org/nomicon/phantom-data.html#generic-parameters-and-drop-checking
157     unsafe fn container_of(ptr: *const T) -> NonNull<ArcInner<T>> {  in container_of()
169         // <https://doc.rust-lang.org/std/ptr/trait.Pointee.html>.  in container_of()
172         // SAFETY: The pointer is in-bounds of an allocation both before and after offsetting the  in container_of()
184 // dynamically-sized type (DST) `U`.
195 // mutable reference when the reference count reaches zero and `T` is dropped.
202 // the reference count reaches zero and `T` is dropped.
207     pub fn new(contents: T, flags: Flags) -> Result<Self, AllocError> {  in new()
208         // INVARIANT: The refcount is initialised to a non-zero value.  in new()
218         // SAFETY: We just created `inner` with a reference count of 1, which is owned by the new  in new()
229     /// The caller must ensure that `inner` points to a valid location and has a non-zero reference
230     /// count, one of which will be owned by the new [`Arc`] instance.
231     unsafe fn from_inner(inner: NonNull<ArcInner<T>>) -> Self {  in from_inner()
242     pub fn into_raw(self) -> *const T {  in into_raw()
255     pub unsafe fn from_raw(ptr: *const T) -> Self {  in from_raw()
261         // reference count held then will be owned by the new `Arc` object.  in from_raw()
270     pub fn as_arc_borrow(&self) -> ArcBorrow<'_, T> {  in as_arc_borrow()
278     pub fn ptr_eq(this: &Self, other: &Self) -> bool {  in ptr_eq()
316     pub fn into_unique_or_drop(self) -> Option<Pin<UniqueArc<T>>> {  in into_unique_or_drop()
322         // If the refcount reaches a non-zero value, then we have destroyed this `Arc` and will  in into_unique_or_drop()
334             // must pin the `UniqueArc` because the values was previously in an `Arc`, and they pin  in into_unique_or_drop()
336             Some(Pin::from(UniqueArc {  in into_unique_or_drop()
349     fn into_foreign(self) -> *mut crate::ffi::c_void {  in into_foreign()
353     unsafe fn from_foreign(ptr: *mut crate::ffi::c_void) -> Self {  in from_foreign()
360         // holds a reference count increment that is transferrable to us.  in from_foreign()
364     unsafe fn borrow<'a>(ptr: *mut crate::ffi::c_void) -> ArcBorrow<'a, T> {  in borrow()
374     unsafe fn borrow_mut<'a>(ptr: *mut crate::ffi::c_void) -> ArcBorrow<'a, T> {  in borrow_mut()
384     fn deref(&self) -> &Self::Target {  in deref()
392     fn as_ref(&self) -> &T {  in as_ref()
398     fn clone(&self) -> Self {  in clone()
416         // touch `refcount` after it's decremented to a non-zero value because another thread/CPU  in drop()
426             // The count reached zero, we must free the memory.  in drop()
435     fn from(item: UniqueArc<T>) -> Self {  in from()
440 impl<T: ?Sized> From<Pin<UniqueArc<T>>> for Arc<T> {
441     fn from(item: Pin<UniqueArc<T>>) -> Self {  in from()
443         unsafe { Pin::into_inner_unchecked(item).inner }  in from()
453 /// over `&Arc<T>` because the latter results in a double-indirection: a pointer (shared reference)
470 /// fn do_something(e: ArcBorrow<'_, Example>) -> Arc<Example> {
518     fn clone(&self) -> Self {  in clone()
533     unsafe fn new(inner: NonNull<ArcInner<T>>) -> Self {  in new()
547     /// * For the duration of the lifetime annotated on this `ArcBorrow`, the reference count must
551     pub unsafe fn from_raw(ptr: *const T) -> Self {  in from_raw()
556         // SAFETY: The caller promises that the value remains valid since the reference count must  in from_raw()
564     fn from(b: ArcBorrow<'_, T>) -> Self {  in from()
565         // SAFETY: The existence of `b` guarantees that the refcount is non-zero. `ManuallyDrop`  in from()
577     fn deref(&self) -> &Self::Target {  in deref()
590 /// `inner` always has a reference count of 1.
606 /// fn test() -> Result<Arc<Example>> {
629 /// fn test() -> Result<Arc<Example>> {
649 /// fn test() -> Result<Arc<Example>> {
650 ///     let mut pinned = Pin::from(UniqueArc::new(Example { a: 10, b: 20 }, GFP_KERNEL)?);
664     pub fn new(value: T, flags: Flags) -> Result<Self, AllocError> {  in new()
666             // INVARIANT: The newly-created object has a refcount of 1.  in new()
672     pub fn new_uninit(flags: Flags) -> Result<UniqueArc<MaybeUninit<T>>, AllocError> {  in new_uninit()
673         // INVARIANT: The refcount is initialised to a non-zero value.  in new_uninit()
678                 data <- init::uninit::<T, AllocError>(),  in new_uninit()
683             // INVARIANT: The newly-created object has a refcount of 1.  in new_uninit()
692     pub fn write(mut self, value: T) -> UniqueArc<T> {  in write()
704     pub unsafe fn assume_init(self) -> UniqueArc<T> {  in assume_init()
714     pub fn init_with<E>(mut self, init: impl Init<T, E>) -> core::result::Result<UniqueArc<T>, E> {  in init_with()
723     /// Pin-initialize `self` using the given pin-initializer.
727     ) -> core::result::Result<Pin<UniqueArc<T>>, E> {  in pin_init_with()
728         // SAFETY: The supplied pointer is valid for initialization and we will later pin the value  in pin_init_with()
738 impl<T: ?Sized> From<UniqueArc<T>> for Pin<UniqueArc<T>> {  implementation
739     fn from(obj: UniqueArc<T>) -> Self {  in from()
740         // SAFETY: It is not possible to move/replace `T` inside a `Pin<UniqueArc<T>>` (unless `T`  in from()
741         // is `Unpin`), so it is ok to convert it to `Pin<UniqueArc<T>>`.  in from()
742         unsafe { Pin::new_unchecked(obj) }  in from()
749     fn deref(&self) -> &Self::Target {  in deref()
755     fn deref_mut(&mut self) -> &mut Self::Target {  in deref_mut()
764     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()
770     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()
776     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()
782     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()