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
32 /// Types that are _always_ reference counted.
35 /// Additionally, it allows users to convert from a shared reference `&T` to an owned reference
39 /// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted
44 /// Implementers must ensure that increments to the reference count keep the object alive in memory
47 /// Implementers must also ensure that all instances are reference-counted. (Otherwise they
51     /// Increments the reference count on the object.
54     /// Decrements the reference count on the object.
60     /// Callers must ensure that there was a previous matching increment to the reference count,
61     /// and that the object is no longer used after its reference count is decremented (as it may
68 /// An owned reference to an always-reference-counted object.
70 /// The object's reference count is automatically decremented when an instance of [`ARef`] is
76 /// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`ARef`] instance. In
77 /// particular, the [`ARef`] instance owns an increment on the underlying object's reference count.
83 // SAFETY: It is safe to send `ARef<T>` to another thread when the underlying `T` is `Sync` because
84 // it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally, it needs
86 // mutable reference, for example, when the reference count reaches zero and `T` is dropped.
87 unsafe impl<T: AlwaysRefCounted + Sync + Send> Send for ARef<T> {}
89 // SAFETY: It is safe to send `&ARef<T>` to another thread when the underlying `T` is `Sync`
90 // because it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally,
92 // `ARef<T>` on that thread, so the thread may ultimately access `T` using a mutable reference, for
93 // example, when the reference count reaches zero and `T` is dropped.
94 unsafe impl<T: AlwaysRefCounted + Sync + Send> Sync for ARef<T> {}
102     /// It takes over an increment of the reference count on the underlying object.
106     /// Callers must ensure that the reference count was incremented at least once, and that they
108     /// must not use the underlying object anymore -- it is only safe to do so via the newly
110     pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
128     /// use kernel::sync::aref::{ARef, AlwaysRefCounted};
146     pub fn into_raw(me: Self) -> NonNull<T> {
152     fn clone(&self) -> Self {
162     fn deref(&self) -> &Self::Target {
169     fn from(b: &T) -> Self {
178         // SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to
190     fn eq(&self, other: &ARef<U>) -> bool {
196 // SAFETY: `into_foreign` returns a pointer from `NonNull::as_ptr`, so it's non-null. The
211     fn into_foreign(self) -> *mut c_void {
216     unsafe fn from_foreign(ptr: *mut c_void) -> Self {
227     unsafe fn borrow<'a>(ptr: *mut c_void) -> &'a T {
234     unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> &'a T {
246     fn eq(&self, other: &&U) -> bool {