Lines Matching +full:reference +full:- +full:sync

1 // SPDX-License-Identifier: GPL-2.0
3 //! Internal reference counting support.
5 //! Many C types already have their own reference counting mechanism (e.g. by storing a
6 //! `refcount_t`). This module provides support for directly using their internal reference count
7 //! from Rust; instead of making users have to use an additional Rust-reference count in the form of
12 //! implementation of the `get_` and `put_` pattern used in C for reference counting.
15 //! for accessing the internal reference count of an object of the `MyType` type.
17 //! [`Arc`]: crate::sync::Arc
18 //! [`Arc<T>`]: crate::sync::Arc
22 /// Types that are _always_ reference counted.
25 /// Additionally, it allows users to convert from a shared reference `&T` to an owned reference
29 /// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted
34 /// Implementers must ensure that increments to the reference count keep the object alive in memory
37 /// Implementers must also ensure that all instances are reference-counted. (Otherwise they
41     /// Increments the reference count on the object.
44     /// Decrements the reference count on the object.
50     /// Callers must ensure that there was a previous matching increment to the reference count,
51     /// and that the object is no longer used after its reference count is decremented (as it may
58 /// An owned reference to an always-reference-counted object.
60 /// The object's reference count is automatically decremented when an instance of [`ARef`] is
66 /// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`ARef`] instance. In
67 /// particular, the [`ARef`] instance owns an increment on the underlying object's reference count.
73 // SAFETY: It is safe to send `ARef<T>` to another thread when the underlying `T` is `Sync` because
74 // it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally, it needs
76 // mutable reference, for example, when the reference count reaches zero and `T` is dropped.
77 unsafe impl<T: AlwaysRefCounted + Sync + Send> Send for ARef<T> {}
79 // SAFETY: It is safe to send `&ARef<T>` to another thread when the underlying `T` is `Sync`
80 // because it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally,
82 // `ARef<T>` on that thread, so the thread may ultimately access `T` using a mutable reference, for
83 // example, when the reference count reaches zero and `T` is dropped.
84 unsafe impl<T: AlwaysRefCounted + Sync + Send> Sync for ARef<T> {}
92     /// It takes over an increment of the reference count on the underlying object.
96     /// Callers must ensure that the reference count was incremented at least once, and that they
98     /// must not use the underlying object anymore -- it is only safe to do so via the newly
100     pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {  in from_raw()
118     /// use kernel::sync::aref::{ARef, AlwaysRefCounted};
136     pub fn into_raw(me: Self) -> NonNull<T> {  in into_raw()
142     fn clone(&self) -> Self {  in clone()
152     fn deref(&self) -> &Self::Target {  in deref()
159     fn from(b: &T) -> Self {  in from()
168         // SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to  in drop()
180     fn eq(&self, other: &ARef<U>) -> bool {  in eq()
191     fn eq(&self, other: &&U) -> bool {  in eq()