Lines Matching +full:pin +full:- +full:count
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
34 pin::Pin,
41 /// A reference-counted pointer to an instance of `T`.
43 /// The reference count is incremented when new instances of [`Arc`] are created, and decremented
44 /// when they are dropped. When the count reaches zero, the underlying `T` is also dropped.
48 /// The reference count on an instance of [`Arc`] is always non-zero.
137 // meaningful with respect to dropck - but this may change in the future so this is left here
140 // See <https://doc.rust-lang.org/nomicon/phantom-data.html#generic-parameters-and-drop-checking>
159 unsafe fn container_of(ptr: *const T) -> NonNull<ArcInner<T>> {
171 // <https://doc.rust-lang.org/std/ptr/trait.Pointee.html>.
174 // SAFETY: The pointer is in-bounds of an allocation both before and after offsetting the
186 // dynamically-sized type (DST) `U`.
197 // mutable reference when the reference count reaches zero and `T` is dropped.
204 // the reference count reaches zero and `T` is dropped.
211 fn try_pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Self::PinnedSelf, E>
219 fn try_init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E>
229 pub fn new(contents: T, flags: Flags) -> Result<Self, AllocError> {
230 // INVARIANT: The refcount is initialised to a non-zero value.
239 // SAFETY: We just created `inner` with a reference count of 1, which is owned by the new
250 /// The caller must ensure that `inner` points to a valid location and has a non-zero reference
251 /// count, one of which will be owned by the new [`Arc`] instance.
252 unsafe fn from_inner(inner: NonNull<ArcInner<T>>) -> Self {
263 pub fn into_raw(self) -> *const T {
271 pub fn as_ptr(this: &Self) -> *const T {
285 pub unsafe fn from_raw(ptr: *const T) -> Self {
291 // reference count held then will be owned by the new `Arc` object.
300 pub fn as_arc_borrow(&self) -> ArcBorrow<'_, T> {
308 pub fn ptr_eq(this: &Self, other: &Self) -> bool {
346 pub fn into_unique_or_drop(this: Self) -> Option<Pin<UniqueArc<T>>> {
352 // If the refcount reaches a non-zero value, then we have destroyed this `Arc` and will
359 // must pin the `UniqueArc` because the values was previously in an `Arc`, and they pin
361 Some(Pin::from(UniqueArc {
378 fn into_foreign(self) -> *mut c_void {
382 unsafe fn from_foreign(ptr: *mut c_void) -> Self {
389 // holds a reference count increment that is transferrable to us.
393 unsafe fn borrow<'a>(ptr: *mut c_void) -> ArcBorrow<'a, T> {
403 unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> ArcBorrow<'a, T> {
413 fn deref(&self) -> &Self::Target {
421 fn as_ref(&self) -> &T {
446 fn borrow(&self) -> &T {
452 fn clone(&self) -> Self {
470 // The count reached zero, we must free the memory.
479 fn from(item: UniqueArc<T>) -> Self {
484 impl<T: ?Sized> From<Pin<UniqueArc<T>>> for Arc<T> {
485 fn from(item: Pin<UniqueArc<T>>) -> Self {
487 unsafe { Pin::into_inner_unchecked(item).inner }
497 /// over `&Arc<T>` because the latter results in a double-indirection: a pointer (shared reference)
514 /// fn do_something(e: ArcBorrow<'_, Example>) -> Arc<Example> {
562 fn clone(&self) -> Self {
577 unsafe fn new(inner: NonNull<ArcInner<T>>) -> Self {
591 /// * For the duration of the lifetime annotated on this `ArcBorrow`, the reference count must
595 pub unsafe fn from_raw(ptr: *const T) -> Self {
600 // SAFETY: The caller promises that the value remains valid since the reference count must
608 fn from(b: ArcBorrow<'_, T>) -> Self {
609 // SAFETY: The existence of `b` guarantees that the refcount is non-zero. `ManuallyDrop`
621 fn deref(&self) -> &Self::Target {
634 /// `inner` always has a reference count of 1.
650 /// fn test() -> Result<Arc<Example>> {
673 /// fn test() -> Result<Arc<Example>> {
693 /// fn test() -> Result<Arc<Example>> {
694 /// let mut pinned = Pin::from(UniqueArc::new(Example { a: 10, b: 20 }, GFP_KERNEL)?);
707 type PinnedSelf = Pin<Self>;
710 fn try_pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Self::PinnedSelf, E>
718 fn try_init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E>
729 fn write_init<E>(mut self, init: impl Init<T, E>) -> Result<Self::Initialized, E> {
738 fn write_pin_init<E>(mut self, init: impl PinInit<T, E>) -> Result<Pin<Self::Initialized>, E> {
741 // slot is valid and will not be moved, because we pin it later.
750 pub fn new(value: T, flags: Flags) -> Result<Self, AllocError> {
752 // INVARIANT: The newly-created object has a refcount of 1.
758 pub fn new_uninit(flags: Flags) -> Result<UniqueArc<MaybeUninit<T>>, AllocError> {
759 // INVARIANT: The refcount is initialised to a non-zero value.
763 data <- pin_init::uninit::<T, AllocError>(),
768 // INVARIANT: The newly-created object has a refcount of 1.
777 pub fn write(mut self, value: T) -> UniqueArc<T> {
789 pub unsafe fn assume_init(self) -> UniqueArc<T> {
799 pub fn init_with<E>(mut self, init: impl Init<T, E>) -> core::result::Result<UniqueArc<T>, E> {
808 /// Pin-initialize `self` using the given pin-initializer.
812 ) -> core::result::Result<Pin<UniqueArc<T>>, E> {
813 // SAFETY: The supplied pointer is valid for initialization and we will later pin the value
823 impl<T: ?Sized> From<UniqueArc<T>> for Pin<UniqueArc<T>> {
824 fn from(obj: UniqueArc<T>) -> Self {
825 // SAFETY: It is not possible to move/replace `T` inside a `Pin<UniqueArc<T>>` (unless `T`
826 // is `Unpin`), so it is ok to convert it to `Pin<UniqueArc<T>>`.
827 unsafe { Pin::new_unchecked(obj) }
834 fn deref(&self) -> &Self::Target {
840 fn deref_mut(&mut self) -> &mut Self::Target {
868 fn borrow(&self) -> &T {
893 fn borrow_mut(&mut self) -> &mut T {
899 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
905 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
911 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
917 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {