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
33     pin::Pin,
40 /// A reference-counted pointer to an instance of `T`.
42 /// The reference count is incremented when new instances of [`Arc`] are created, and decremented
43 /// when they are dropped. When the count reaches zero, the underlying `T` is also dropped.
47 /// The reference count on an instance of [`Arc`] is always non-zero.
148     unsafe fn container_of(ptr: *const T) -> NonNull<ArcInner<T>> {  in container_of()
160         // <https://doc.rust-lang.org/std/ptr/trait.Pointee.html>.  in container_of()
163         // SAFETY: The pointer is in-bounds of an allocation both before and after offsetting the  in container_of()
178 // dynamically-sized type (DST) `U`.
187 // mutable reference when the reference count reaches zero and `T` is dropped.
194 // the reference count reaches zero and `T` is dropped.
199     pub fn new(contents: T, flags: Flags) -> Result<Self, AllocError> {  in new()
200         // INVARIANT: The refcount is initialised to a non-zero value.  in new()
209         // SAFETY: We just created `inner` with a reference count of 1, which is owned by the new  in new()
220     /// The caller must ensure that `inner` points to a valid location and has a non-zero reference
221     /// count, one of which will be owned by the new [`Arc`] instance.
222     unsafe fn from_inner(inner: NonNull<ArcInner<T>>) -> Self {  in from_inner()
233     pub fn into_raw(self) -> *const T {  in into_raw()
246     pub unsafe fn from_raw(ptr: *const T) -> Self {  in from_raw()
252         // reference count held then will be owned by the new `Arc` object.  in from_raw()
261     pub fn as_arc_borrow(&self) -> ArcBorrow<'_, T> {  in as_arc_borrow()
269     pub fn ptr_eq(this: &Self, other: &Self) -> bool {  in ptr_eq()
307     pub fn into_unique_or_drop(self) -> Option<Pin<UniqueArc<T>>> {  in into_unique_or_drop()
313         // If the refcount reaches a non-zero value, then we have destroyed this `Arc` and will  in into_unique_or_drop()
325             // must pin the `UniqueArc` because the values was previously in an `Arc`, and they pin  in into_unique_or_drop()
327             Some(Pin::from(UniqueArc {  in into_unique_or_drop()
339     fn into_foreign(self) -> *const core::ffi::c_void {  in into_foreign()
343     unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {  in borrow()
353     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {  in from_foreign()
356         // holds a reference count increment that is transferrable to us.  in from_foreign()
364     fn deref(&self) -> &Self::Target {  in deref()
372     fn as_ref(&self) -> &T {  in as_ref()
378     fn clone(&self) -> Self {  in clone()
392         // touch `refcount` after it's decremented to a non-zero value because another thread/CPU  in drop()
402             // The count reached zero, we must free the memory.  in drop()
411     fn from(item: UniqueArc<T>) -> Self {  in from()
416 impl<T: ?Sized> From<Pin<UniqueArc<T>>> for Arc<T> {
417     fn from(item: Pin<UniqueArc<T>>) -> Self {  in from()
419         unsafe { Pin::into_inner_unchecked(item).inner }  in from()
429 /// over `&Arc<T>` because the latter results in a double-indirection: a pointer (shared reference)
446 /// fn do_something(e: ArcBorrow<'_, Example>) -> Arc<Example> {
494     fn clone(&self) -> Self {  in clone()
509     unsafe fn new(inner: NonNull<ArcInner<T>>) -> Self {  in new()
523     /// * For the duration of the lifetime annotated on this `ArcBorrow`, the reference count must
527     pub unsafe fn from_raw(ptr: *const T) -> Self {  in from_raw()
532         // SAFETY: The caller promises that the value remains valid since the reference count must  in from_raw()
540     fn from(b: ArcBorrow<'_, T>) -> Self {  in from()
541         // SAFETY: The existence of `b` guarantees that the refcount is non-zero. `ManuallyDrop`  in from()
553     fn deref(&self) -> &Self::Target {  in deref()
566 /// `inner` always has a reference count of 1.
582 /// fn test() -> Result<Arc<Example>> {
605 /// fn test() -> Result<Arc<Example>> {
625 /// fn test() -> Result<Arc<Example>> {
626 ///     let mut pinned = Pin::from(UniqueArc::new(Example { a: 10, b: 20 }, GFP_KERNEL)?);
640     pub fn new(value: T, flags: Flags) -> Result<Self, AllocError> {  in new()
642             // INVARIANT: The newly-created object has a refcount of 1.  in new()
648     pub fn new_uninit(flags: Flags) -> Result<UniqueArc<MaybeUninit<T>>, AllocError> {  in new_uninit()
649         // INVARIANT: The refcount is initialised to a non-zero value.  in new_uninit()
654                 data <- init::uninit::<T, AllocError>(),  in new_uninit()
659             // INVARIANT: The newly-created object has a refcount of 1.  in new_uninit()
668     pub fn write(mut self, value: T) -> UniqueArc<T> {  in write()
680     pub unsafe fn assume_init(self) -> UniqueArc<T> {  in assume_init()
690     pub fn init_with<E>(mut self, init: impl Init<T, E>) -> core::result::Result<UniqueArc<T>, E> {  in init_with()
699     /// Pin-initialize `self` using the given pin-initializer.
703     ) -> core::result::Result<Pin<UniqueArc<T>>, E> {  in pin_init_with()
704         // SAFETY: The supplied pointer is valid for initialization and we will later pin the value  in pin_init_with()
714 impl<T: ?Sized> From<UniqueArc<T>> for Pin<UniqueArc<T>> {  implementation
715     fn from(obj: UniqueArc<T>) -> Self {  in from()
716         // SAFETY: It is not possible to move/replace `T` inside a `Pin<UniqueArc<T>>` (unless `T`  in from()
717         // is `Unpin`), so it is ok to convert it to `Pin<UniqueArc<T>>`.  in from()
718         unsafe { Pin::new_unchecked(obj) }  in from()
725     fn deref(&self) -> &Self::Target {  in deref()
731     fn deref_mut(&mut self) -> &mut Self::Target {  in deref_mut()
740     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()
746     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()
752     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()
758     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()