New trait OwnableRefCounted for ARef<->Owned conversion.
Subsystems (6)
v6 cover New trait OwnableRefCounted for ARef<->Owned conversion.
This allows to convert between ARef<T> and Owned<T> by implementing the new trait OwnedRefCounted.
This way we will have a shared/unique reference counting scheme for types with built-in refcounts in analogy to Arc/UniqueArc.
---
Changes in v6:
- Changed comments/formatting as suggested by Miguel Ojeda
- Included and used new config flag RUSTC_HAS_DO_NOT_RECOMMEND,
thus no changes to types.rs will be needed when the attribute becomes available.
- Fixed commit message for Owned patch.
- Link to v5: https://lore.kernel.org/r/[email protected]
Changes in v5:
- Rebase the whole thing on top of the Ownable/Owned traits by Asahi Lina.
- Rename AlwaysRefCounted to RefCounted and make AlwaysRefCounted a marker trait instead to allow to obtain an ARef<T> from an &T,
which (as Alice pointed out) is unsound when combined with UniqueRef/Owned.
- Change the Trait design and naming to implement this feature, UniqueRef/UniqueRefCounted is dropped in favor of Ownable/Owned and OwnableRefCounted is used to provide the functions to convert between Owned and ARef.
- Link to v4: https://lore.kernel.org/r/[email protected]
Changes in v4:
- Just a minor change in naming by request from Andreas Hindborg, try_shared_to_unique() -> try_from_shared(), unique_to_shared() -> into_shared(),
which is more in line with standard Rust naming conventions.
- Link to v3: https://lore.kernel.org/r/Z8Wuud2UQX6Yukyr@mango
---
Asahi Lina (1):
rust: types: Add Ownable/Owned types
Miguel Ojeda (1):
rust: kbuild: provide RUSTC_HAS_DO_NOT_RECOMMEND symbol
Oliver Mangold (3):
rust: make Owned::into_raw() and Owned::from_raw() public
rust: rename AlwaysRefCounted to RefCounted
rust: adding OwnableRefCounted and SimpleOwnableRefCounted
init/Kconfig | 3 + rust/kernel/block/mq/request.rs | 10 +- rust/kernel/cred.rs | 8 +- rust/kernel/device.rs | 8 +- rust/kernel/fs/file.rs | 10 +- rust/kernel/pid_namespace.rs | 8 +- rust/kernel/task.rs | 6 +- rust/kernel/types.rs | 429 ++++++++++++++++++++++++++++++++++++++-- 8 files changed, 451 insertions(+), 31 deletions(-)
---
base-commit: 4b2ee22fe32ea9b255926effbb6f26450607c391
change-id: 20250305-unique-ref-29fcd675f9e9
Best regards,
Signature · 1 line
Oliver Mangold <[email protected]>
PATCH v6 1/5 rust: types: Add Ownable/Owned types
From: Asahi Lina <[email protected]>
By analogy to AlwaysRefCounted and ARef, an Ownable type is a (typically C FFI) type that *may* be owned by Rust, but need not be. Unlike AlwaysRefCounted, this mechanism expects the reference to be unique within Rust, and does not allow cloning.
Conceptually, this is similar to a KBox<T>, except that it delegates resource management to the T instead of using a generic allocator.
--- rust/kernel/types.rs | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+)
rust/kernel/types.rs +110 -0
@@ -551,6 +551,116 @@ fn drop(&mut self) { } } +/// Types that may be owned by Rust code or borrowed, but have a lifetime managed by C code. +/// +/// It allows such types to define their own custom destructor function to be called when +/// a Rust-owned reference is dropped. +/// +/// This is usually implemented by wrappers to existing structures on the C side of the code. +/// +/// # Safety +/// +/// Implementers must ensure that any objects borrowed directly as `&T` stay alive for the duration +/// of the lifetime, and that any objects owned by Rust as `Owned<T>`) stay alive while that owned +/// reference exists, until the [`Ownable::release()`] trait method is called. +pub unsafe trait Ownable { +/// Releases the object (frees it or returns it to foreign ownership). +/// +/// # Safety +/// +/// Callers must ensure that the object is no longer referenced after this call. +unsafe fn release (this:NonNull <Self >); +} + +/// A subtrait of Ownable that asserts that an `Owned<T>` Rust reference is not only unique +/// within Rust and keeps the `T` alive, but also guarantees that the C code follows the +/// usual mutable reference requirements. That is, the kernel will never mutate the +/// `T` (excluding internal mutability that follows the usual rules) while Rust owns it. +/// +/// When this type is implemented for an [`Ownable`] type, it allows `Owned<T>` to be +/// dereferenced into a &mut T. +/// +/// # Safety +/// +/// Implementers must ensure that the kernel never mutates the underlying type while +/// Rust owns it. +pub unsafe trait OwnableMut :Ownable {} + +/// An owned reference to an ownable kernel object. +/// +/// The object is automatically freed or released when an instance of [`Owned`] is +/// dropped. +/// +/// # Invariants +/// +/// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`Owned`] instance. +pub struct Owned <T :Ownable > { + ptr:NonNull <T >, + _p:PhantomData <T >, +} + +// SAFETY: It is safe to send `Owned<T>` to another thread when the underlying `T` is `Send` because +// it effectively means sending a unique `&mut T` pointer (which is safe because `T` is `Send`). +unsafe impl <T :Ownable +Send >Send for Owned <T > {} + +// SAFETY: It is safe to send `&Owned<T>` to another thread when the underlying `T` is `Sync` +// because it effectively means sharing `&T` (which is safe because `T` is `Sync`). +unsafe impl <T :Ownable +Sync >Sync for Owned <T > {} + +impl <T :Ownable >Owned <T > { +/// Creates a new instance of [`Owned`]. +/// +/// It takes over ownership of the underlying object. +/// +/// # Safety +/// +/// Callers must ensure that the underlying object is acquired and can be considered owned by +/// Rust. +pub (crate )unsafe fn from_raw (ptr:NonNull <T >) ->Self { +// INVARIANT: The safety requirements guarantee that the new instance now owns the +// reference. +Self { + ptr, + _p:PhantomData , + } + } + +/// Consumes the `Owned`, returning a raw pointer. +/// +/// This function does not actually relinquish ownership of the object. +/// After calling this function, the caller is responsible for ownership previously managed +/// by the `Owned`. +#[allow(dead_code)] +pub (crate )fn into_raw (me:Self ) ->NonNull <T > { +ManuallyDrop ::new (me).ptr + } +} + +impl <T :Ownable >Deref for Owned <T > { +type Target =T ; + +fn deref (&self) -> &Self ::Target { +// SAFETY: The type invariants guarantee that the object is valid. +unsafe { self.ptr.as_ref () } + } +} + +impl <T :Ownable +OwnableMut >DerefMut for Owned <T > { +fn deref_mut (&mut self) -> &mut Self ::Target { +// SAFETY: The type invariants guarantee that the object is valid, +// and that we can safely return a mutable reference to it. +unsafe { self.ptr.as_mut () } + } +} + +impl <T :Ownable >Drop for Owned <T > { +fn drop (&mut self) { +// SAFETY: The type invariants guarantee that the `Owned` owns the object we're about to +// release. +unsafe {T ::release (self.ptr) }; + } +} +/// A sum type that always holds either a value of type `L` or `R`. /// /// # Examples
Signature · 1 line
2.48.1
Alice Ryhl
reviewerRe: [PATCH v6 1/5] rust: types: Add Ownable/Owned types
Quoted 11 lines · Oliver Mangold
From: Asahi Lina <[email protected]>
By analogy to AlwaysRefCounted and ARef, an Ownable type is a (typically C FFI) type that *may* be owned by Rust, but need not be. Unlike AlwaysRefCounted, this mechanism expects the reference to be unique within Rust, and does not allow cloning.
Conceptually, this is similar to a KBox<T>, except that it delegates resource management to the T instead of using a generic allocator.
Signed-off-by Asahi Lina <[email protected]>
You can't send a patch by others without adding your own SoB.
Alice
PATCH v6 2/5 rust: make Owned::into_raw() and Owned::from_raw() public
In reply to Oliver MangoldIt might be necessary to be used from some drivers containing C code like, e.g. binder. It basically is needed for every implementation of an Ownable outside of the kernel crate. Also the examples for OwnableRefCounted need it.
--- rust/kernel/types.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-)
rust/kernel/types.rs +2 -3
@@ -616,7 +616,7 @@ impl<T: Ownable> Owned<T> {/// /// Callers must ensure that the underlying object is acquired and can be considered owned by /// Rust. -pub (crate )unsafe fn from_raw (ptr:NonNull <T >) ->Self { +pub unsafe fn from_raw (ptr:NonNull <T >) ->Self {// INVARIANT: The safety requirements guarantee that the new instance now owns the // reference. Self {
@@ -630,8 +630,7 @@ pub(crate) unsafe fn from_raw(ptr: NonNull<T>) -> Self {/// This function does not actually relinquish ownership of the object. /// After calling this function, the caller is responsible for ownership previously managed /// by the `Owned`. -#[allow(dead_code)] -pub (crate )fn into_raw (me:Self ) ->NonNull <T > { +pub fn into_raw (me:Self ) ->NonNull <T > {ManuallyDrop ::new (me).ptr } }
Signature · 1 line
2.48.1
Alice Ryhl
reviewerRe: [PATCH v6 2/5] rust: make Owned::into_raw() and Owned::from_raw() public
Quoted 6 lines · Oliver Mangold
It might be necessary to be used from some drivers containing C code like, e.g. binder. It basically is needed for every implementation of an Ownable outside of the kernel crate. Also the examples for OwnableRefCounted need it.
Signed-off-by Oliver Mangold <[email protected]>
I would probably just fold this into the previous patch.
Alice
Re: [PATCH v6 2/5] rust: make Owned::into_raw() and Owned::from_raw() public
Quoted 2 lines · Alice Ryhl
You can't send a patch by others without adding your own SoB.
Ok. Sorry, didn't know that.
Quoted 2 lines · Alice Ryhl
I would probably just fold this into the previous patch.
That is okay with different authors? Just leave that authorship with Asahi Lina, then, I assume?
Oliver
Danilo Krummrich
maintainerRe: [PATCH v6 2/5] rust: make Owned::into_raw() and Owned::from_raw() public
Quoted 5 lines · Oliver Mangold
Quoted 1 line · Alice Ryhl
I would probably just fold this into the previous patch.
That is okay with different authors? Just leave that authorship with Asahi Lina, then, I assume?
There is a 'Co-developed-by:' tag, please see [1].
[1] https://docs.kernel.org/process/submitting-patches.html#developer-s-certificate-of-origin-1-1
Re: [PATCH v6 2/5] rust: make Owned::into_raw() and Owned::from_raw() public
Quoted 11 lines · Danilo Krummrich
Quoted 5 lines · Oliver Mangold
Quoted 1 line · Alice Ryhl
I would probably just fold this into the previous patch.
That is okay with different authors? Just leave that authorship with Asahi Lina, then, I assume?
There is a 'Co-developed-by:' tag, please see [1].
[1]
https://docs.kernel.org/process/submitting-patches.html#developer-s-certificate-of-origin-1-1
Ah, okay. Thanks.
Best regards,
Oliver
PATCH v6 3/5 rust: rename AlwaysRefCounted to RefCounted
In reply to Oliver MangoldAlwaysRefCounted will become a marker trait to indicate that it is allowed to obtain an ARef from a &, which cannot be allowed for types which are also Ownable.
--- rust/kernel/block/mq/request.rs | 10 ++++++--- rust/kernel/cred.rs | 8 ++++++-- rust/kernel/device.rs | 8 ++++++-- rust/kernel/fs/file.rs | 10 ++++++--- rust/kernel/pid_namespace.rs | 8 ++++++-- rust/kernel/task.rs | 6 +++++- rust/kernel/types.rs | 45 ++++++++++++++++++++++++----------------- 7 files changed, 64 insertions(+), 31 deletions(-)
rust/kernel/block/mq/request.rs +7 -3
@@ -9,7 +9,7 @@ block::mq::Operations, error::Result, sync::Refcount, - types::{ARef, AlwaysRefCounted, Opaque}, + types::{ARef, AlwaysRefCounted, Opaque, RefCounted}, };use core::{ marker::PhantomData ,
@@ -209,10 +209,10 @@ unsafe impl<T: Operations> Send for Request<T> {}unsafe impl <T :Operations >Sync for Request <T > {}// SAFETY: All instances of `Request<T>` are reference counted. This -// implementation of `AlwaysRefCounted` ensure that increments to the ref count +// implementation of `RefCounted` ensure that increments to the ref count // keeps the object alive in memory at least until a matching reference count // decrement is executed. -unsafe impl <T :Operations >AlwaysRefCounted for Request <T > { +unsafe impl <T :Operations >RefCounted for Request <T > {fn inc_ref (&self) { self.wrapper_ref ().refcount ().inc (); }
@@ -234,3 +234,7 @@ unsafe fn dec_ref(obj: core::ptr::NonNull<Self>) { } } } + +// SAFETY: we currently do not implement `Ownable`, thus it is okay to can obtain an `ARef<Request>` +// from a `&Request` (but this will change in the future). +unsafe impl <T :Operations >AlwaysRefCounted for Request <T > {}
rust/kernel/cred.rs +6 -2
@@ -11,7 +11,7 @@use crate ::{ bindings, task::Kuid , - types::{AlwaysRefCounted ,Opaque }, + types::{AlwaysRefCounted ,Opaque ,RefCounted }, };/// Wraps the kernel's `struct cred`.
@@ -71,7 +71,7 @@ pub fn euid(&self) -> Kuid { }// SAFETY: The type invariants guarantee that `Credential` is always ref-counted. -unsafe impl AlwaysRefCounted for Credential { +unsafe impl RefCounted for Credential {fn inc_ref (&self) {// SAFETY: The existence of a shared reference means that the refcount is nonzero. unsafe { bindings::get_cred (self.0 .get ()) };
@@ -83,3 +83,7 @@ unsafe fn dec_ref(obj: core::ptr::NonNull<Credential>) {unsafe { bindings::put_cred (obj.cast ().as_ptr ()) }; } } + +// SAFETY: We do not implement `Ownable`, thus it is okay to can obtain an `ARef<Credential>` from a +// `&Credential`. +unsafe impl AlwaysRefCounted for Credential {}
rust/kernel/device.rs +6 -2
@@ -7,7 +7,7 @@use crate ::{ bindings, str::CStr , - types::{ARef ,Opaque }, + types::{ARef ,AlwaysRefCounted ,Opaque ,RefCounted }, };use core::{fmt, ptr};
@@ -190,7 +190,7 @@ pub fn property_present(&self, name: &CStr) -> bool { }// SAFETY: Instances of `Device` are always reference-counted. -unsafe impl crate ::types::AlwaysRefCounted for Device { +unsafe impl RefCounted for Device {fn inc_ref (&self) {// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero. unsafe { bindings::get_device (self.as_raw ()) };
@@ -202,6 +202,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<Self>) { } } +// SAFETY: We do not implement `Ownable`, thus it is okay to can obtain an `Device<Task>` from a +// `&Device`. +unsafe impl AlwaysRefCounted for Device {} +// SAFETY: As by the type invariant `Device` can be sent to any thread. unsafe impl Send for Device {}
rust/kernel/fs/file.rs +7 -3
@@ -11,7 +11,7 @@ bindings, cred::Credential, error::{code::*, Error, Result}, - types::{ARef, AlwaysRefCounted, NotThreadSafe, Opaque}, + types::{ARef, AlwaysRefCounted, NotThreadSafe, Opaque, RefCounted}, };use core::ptr;
@@ -190,7 +190,7 @@ unsafe impl Sync for File {}// SAFETY: The type invariants guarantee that `File` is always ref-counted. This implementation // makes `ARef<File>` own a normal refcount. -unsafe impl AlwaysRefCounted for File { +unsafe impl RefCounted for File {#[inline] fn inc_ref (&self) {// SAFETY: The existence of a shared reference means that the refcount is nonzero.
@@ -205,6 +205,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<File>) { } } +// SAFETY: We do not implement `Ownable`, thus it is okay to can obtain an `ARef<File>` from a +/// `&File`. +unsafe impl AlwaysRefCounted for File {} +/// Wraps the kernel's `struct file`. Not thread safe. /// /// This type represents a file that is not known to be safe to transfer across thread boundaries.
@@ -225,7 +229,7 @@ pub struct LocalFile {// SAFETY: The type invariants guarantee that `LocalFile` is always ref-counted. This implementation // makes `ARef<File>` own a normal refcount. -unsafe impl AlwaysRefCounted for LocalFile { +unsafe impl RefCounted for LocalFile {#[inline] fn inc_ref (&self) {// SAFETY: The existence of a shared reference means that the refcount is nonzero.
rust/kernel/pid_namespace.rs +6 -2
@@ -9,7 +9,7 @@use crate ::{ bindings, - types::{AlwaysRefCounted ,Opaque }, + types::{AlwaysRefCounted ,RefCounted ,Opaque }, };use core::ptr;
@@ -44,7 +44,7 @@ pub unsafe fn from_ptr<'a>(ptr: *const bindings::pid_namespace) -> &'a Self { }// SAFETY: Instances of `PidNamespace` are always reference-counted. -unsafe impl AlwaysRefCounted for PidNamespace { +unsafe impl RefCounted for PidNamespace {#[inline] fn inc_ref (&self) {// SAFETY: The existence of a shared reference means that the refcount is nonzero.
@@ -58,6 +58,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<PidNamespace>) { } } +// SAFETY: We do not implement `Ownable`, thus it is okay to can obtain an `ARef<PidNamespace>` +// from a `&PidNamespace`. +unsafe impl AlwaysRefCounted for PidNamespace {} +// SAFETY: // - `PidNamespace::dec_ref` can be called from any thread. // - It is okay to send ownership of `PidNamespace` across thread boundaries.
rust/kernel/task.rs +5 -1
@@ -327,7 +327,7 @@ pub fn wake_up(&self) { }// SAFETY: The type invariants guarantee that `Task` is always refcounted. -unsafe impl crate ::types::AlwaysRefCounted for Task { +unsafe impl crate ::types::RefCounted for Task {fn inc_ref (&self) {// SAFETY: The existence of a shared reference means that the refcount is nonzero. unsafe { bindings::get_task_struct (self.as_ptr ()) };
@@ -339,6 +339,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<Self>) { } } +// SAFETY: We do not implement `Ownable`, thus it is okay to can obtain an `ARef<Task>` from a +// `&Task`. +unsafe impl crate ::types::AlwaysRefCounted for Task {} +impl Kuid {/// Get the current euid. #[inline]
rust/kernel/types.rs +27 -18
117 lines not on this page · raw message
Signature · 1 line
2.48.1
PATCH v6 4/5 rust: kbuild: provide `RUSTC_HAS_DO_NOT_RECOMMEND` symbol
In reply to Oliver MangoldFrom: Miguel Ojeda <[email protected]>
Rust 1.85.0 (current stable version) stabilized [1] #[diagnostic::do_not_recommend] [2].
In order to use it across all supported Rust versions, introduce a new Kconfig symbol for it.
This allows to perform conditional compilation based on it, e.g. on the use site to enable the attribute:
#[cfg_attr(RUSTC_HAS_DO_NOT_RECOMMEND, diagnostic::do_not_recommend)]
impl A for i32 {}An alternative would have been to allow the following warning:
#![allow(unknown_or_malformed_diagnostic_attributes)]
However, that would lose the checking for typos across all versions, which we do not want to lose.
One can also use the Kconfig symbol to allow the warning in older compilers instead, to avoid repeating the cfg_attr line above in all use sites:
#![cfg_attr(
not(RUSTC_HAS_DO_NOT_RECOMMEND),
expect(unknown_or_malformed_diagnostic_attributes)
)]That still loses the checking for typos in older versions, but we still keep it in newer ones, thus we should still catch mistakes eventually.
In this case we can promote it to expect as shown above, so that we do not forget to remove these lines if we stop using the attribute somewhere.
--- init/Kconfig | 3 +++ 1 file changed, 3 insertions(+)
init/Kconfig +3 -0
@@ -147,6 +147,9 @@ config CC_HAS_COUNTED_BY config RUSTC_HAS_COERCE_POINTEE def_bool RUSTC_VERSION >= 108400 +config RUSTC_HAS_DO_NOT_RECOMMEND + def_bool RUSTC_VERSION >= 108500 + config PAHOLE_VERSION int default $(shell,$(srctree)/scripts/pahole-version.sh $(PAHOLE))
Signature · 1 line
2.48.1
PATCH v6 5/5 rust: adding OwnableRefCounted and SimpleOwnableRefCounted
In reply to Oliver MangoldTypes implementing one of these traits can safely convert between an ARef<T> and an Owned<T>.
--- rust/kernel/types.rs | 275 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 275 insertions(+)
rust/kernel/types.rs +275 -0
@@ -552,6 +552,12 @@ fn from(b: &T) -> Self { } } +impl <T :OwnableRefCounted >From <Owned <T >>for ARef <T > { +fn from (b:Owned <T >) ->Self { +T ::into_shared (b) + } +} +impl <T :RefCounted >Drop for ARef <T > {fn drop (&mut self) {// SAFETY: The type invariants guarantee that the `ARef` owns the reference
@@ -669,6 +675,275 @@ fn drop(&mut self) { } } +/// A trait for objects that can be wrapped in either one of the reference types [`Owned`] and +/// [`ARef`]. +/// +/// # Safety +/// +/// Implementers must ensure that: +/// +/// - Both the safety requirements for [`Ownable`] and [`RefCounted`] are fulfilled. +/// - The uniqueness invariant of [`Owned`] is upheld until dropped. +/// - [`try_from_shared()`](OwnableRefCounted::into_shared) only returns an [`Owned`] if exactly +/// one [`ARef`] exists. +/// - [`into_shared()`](OwnableRefCounted::into_shared) set the reference count to the value which +/// the returned [`ARef`] expects for an object with a single reference +/// in existence. This implies that if [`into_shared()`](OwnableRefCounted::into_shared) is left +/// on the default implementation, which just rewraps the underlying object, the reference count +/// needs not to be modified when converting a [`Owned`] to an [`ARef`]. +/// +/// # Examples +/// +/// A minimal example implementation of [`OwnableRefCounted`], [`Ownable`] and its usage with +/// [`ARef`] and [`Owned`] looks like this: +/// +/// ``` +/// # #![expect(clippy::disallowed_names)] +/// use core::cell::Cell; +/// use core::ptr::NonNull; +/// use kernel::alloc::{flags, kbox::KBox, AllocError}; +/// use kernel::types::{ +/// ARef, RefCounted, Owned, Ownable, OwnableRefCounted, +/// }; +/// +/// struct Foo { +/// refcount: Cell<usize>, +/// } +/// +/// impl Foo { +/// fn new() -> Result<Owned<Self>, AllocError> { +/// // Use a `KBox` to handle the actual allocation. +/// let result = KBox::new( +/// Foo { +/// refcount: Cell::new(1), +/// }, +/// flags::GFP_KERNEL, +/// )?; +/// let result = NonNull::new(KBox::into_raw(result)) +/// .expect("Raw pointer to newly allocation KBox is null, this should never happen."); +/// // SAFETY: We just allocated the `Foo`, thus it is valid. +/// Ok(unsafe { Owned::from_raw(result) }) +/// } +/// } +/// +/// // SAFETY: We increment and decrement each time the respective function is called and only free +/// // the `Foo` when the refcount reaches zero. +/// unsafe impl RefCounted for Foo { +/// fn inc_ref(&self) { +/// self.refcount.replace(self.refcount.get() + 1); +/// } +/// +/// unsafe fn dec_ref(this: NonNull<Self>) { +/// // SAFETY: The underlying object is always valid when the function is called. +/// let refcount = unsafe { &this.as_ref().refcount }; +/// let new_refcount = refcount.get() - 1; +/// if new_refcount == 0 { +/// // The `Foo` will be dropped when `KBox` goes out of scope. +/// // SAFETY: The `Box<Foo>` is still alive as the old refcount is 1. +/// unsafe { KBox::from_raw(this.as_ptr()) }; +/// } else { +/// refcount.replace(new_refcount); +/// } +/// } +/// } +/// +/// // SAFETY: We only convert into an `Owned` when the refcount is 1. +/// unsafe impl OwnableRefCounted for Foo { +/// fn try_from_shared(this: ARef<Self>) -> Result<Owned<Self>, ARef<Self>> { +/// if this.refcount.get() == 1 { +/// // SAFETY: The `Foo` is still alive as the refcount is 1. +/// Ok(unsafe { Owned::from_raw(ARef::into_raw(this)) }) +/// } else { +/// Err(this) +/// } +/// } +/// } +/// +/// // SAFETY: We are not `AlwaysRefCounted`. +/// unsafe impl Ownable for Foo { +/// unsafe fn release(this: NonNull<Self>) { +/// // SAFETY: Using `dec_ref()` from `RefCounted` to release is okay, as the refcount is +/// // always 1 for an `Owned<Foo>`. +/// unsafe{ Foo::dec_ref(this) }; +/// } +/// } +/// +/// let foo = Foo::new().unwrap(); +/// let mut foo = ARef::from(foo); +/// { +/// let bar = foo.clone(); +/// assert!(Owned::try_from(bar).is_err()); +/// } +/// assert!(Owned::try_from(foo).is_ok()); +/// ``` +pub unsafe trait OwnableRefCounted :RefCounted +Ownable +Sized { +/// Checks if the [`ARef`] is unique and convert it to an [`Owned`] it that is that case. +/// Otherwise it returns again an [`ARef`] to the same underlying object. +fn try_from_shared (this:ARef <Self >) ->Result <Owned <Self >,ARef <Self >>; +/// Converts the [`Owned`] into an [`ARef`]. + +fn into_shared (this:Owned <Self >) ->ARef <Self > { +// SAFETY: Safe by the requirements on implementing the trait. +unsafe {ARef ::from_raw (Owned ::into_raw (this)) } + } +} + +/// This trait allows to implement all of [`Ownable`], [`RefCounted`] and +/// [`OwnableRefCounted`] together in a simplified way, +/// only requiring to provide the methods [`inc_ref()`](SimpleOwnableRefCounted::inc_ref), +/// [`dec_ref()`](SimpleOwnableRefCounted::dec_ref), +/// and [`is_unique()`](SimpleOwnableRefCounted::is_unique). +/// +/// For non-standard cases where conversion between [`Ownable`] and [`RefCounted`] needs +/// or [`Ownable::release()`] and [`RefCounted::dec_ref()`] cannot be the same method, +/// [`Ownable`], [`RefCounted`] and [`OwnableRefCounted`] should be implemented manually. +/// +/// # Safety +/// +/// Implementers must ensure that: +/// +/// - Both the safety requirements as for [`Ownable`] and [`RefCounted`] are fulfilled. +/// - [`is_unique`](SimpleOwnableRefCounted::is_unique) must only return `true` in case only one +/// [`ARef`] exists and it is impossible for one to be obtained other than by cloning an existing +/// [`ARef`] or converting an [`Owned`] to an [`ARef`]. +/// - It is safe to convert an unique [`ARef`] into an [`Owned`] simply by re-wrapping the +/// underlying object without modifying the refcount. +/// +/// # Examples +/// +/// A minimal example implementation of [`SimpleOwnableRefCounted`] +/// and its usage with [`ARef`] and [`Owned`] looks like this: +/// +/// ``` +/// # #![expect(clippy::disallowed_names)] +/// use core::cell::Cell; +/// use core::ptr::NonNull; +/// use kernel::alloc::{flags, kbox::KBox, AllocError}; +/// use kernel::types::{ +/// ARef, SimpleOwnableRefCounted, Owned, +/// }; +/// +/// struct Foo { +/// refcount: Cell<usize>, +/// } +/// +/// impl Foo { +/// fn new() -> Result<Owned<Self>, AllocError> { +/// // Use a KBox to handle the actual allocation. +/// let result = KBox::new( +/// Foo { +/// refcount: Cell::new(1), +/// }, +/// flags::GFP_KERNEL, +/// )?; +/// let result = NonNull::new(KBox::into_raw(result)) +/// .expect("Raw pointer to newly allocation KBox is null, this should never happen."); +/// // SAFETY: We just allocated the `Foo`, thus it is valid. +/// Ok(unsafe { Owned::from_raw(result) }) +/// } +/// } +/// +/// // SAFETY: we ensure that: +/// // - The `Foo` is only dropped when the refcount is zero. +/// // - `is_unique()` only returns `true` when the refcount is 1. +/// unsafe impl SimpleOwnableRefCounted for Foo { +/// fn inc_ref(&self) { +/// self.refcount.replace(self.refcount.get() + 1); +/// } +/// +/// unsafe fn dec_ref(this: NonNull<Self>) { +/// // SAFETY: The underlying object is always valid when the function is called. +/// let refcount = unsafe { &this.as_ref().refcount }; +/// let new_refcount = refcount.get() - 1; +/// if new_refcount == 0 { +/// // The `Foo` will be dropped when KBox goes out of scope. +/// // SAFETY: The `Box<Foo>` is still alive as the old refcount is 1. +/// unsafe { KBox::from_raw(this.as_ptr()) }; +/// } else { +/// refcount.replace(new_refcount); +/// } +/// } +/// +/// fn is_unique(&self) -> bool { +/// self.refcount.get() == 1 +/// } +/// } +/// +/// let foo = Foo::new().unwrap(); +/// let mut foo = ARef::from(foo); +/// { +/// let bar = foo.clone(); +/// assert!(Owned::try_from(bar).is_err()); +/// } +/// assert!(Owned::try_from(foo).is_ok()); +/// ``` +pub unsafe trait SimpleOwnableRefCounted { +/// Checks if exactly one [`ARef`] to the object exists. In case the object is [`Sync`], the +/// check needs to be race-free. +fn is_unique (&self) ->bool ; + +/// Increments the reference count on the object. +fn inc_ref (&self); + +/// Decrements the reference count on the object when the [`SimpleOwnableRefCounted`] is +/// dropped. +/// +/// Frees the object when the count reaches zero. +/// +/// # Safety +/// +/// The safety constraints for [`RefCounted::dec_ref`] and [`Ownable::release`] both apply to +/// this method, as it will be used to implement both of these traits. +unsafe fn dec_ref (obj:NonNull <Self >); +} + +#[cfg_attr( RUSTC_HAS_DO_NOT_RECOMMEND , diagnostic::do_not_recommend)] +// SAFETY: Safe by the requirements on implementation of [`SimpleOwnableRefCounted`]. +unsafe impl <T :SimpleOwnableRefCounted >OwnableRefCounted for T { +fn try_from_shared (this:ARef <Self >) ->Result <Owned <Self >,ARef <Self >> { +if T ::is_unique (&*this) { +// SAFETY: Safe by the requirements on implementation of [`SimpleOwnable`]. +Ok (unsafe {Owned ::from_raw (ARef ::into_raw (this)) }) + }else { +Err (this) + } + } +} + +#[cfg_attr( RUSTC_HAS_DO_NOT_RECOMMEND , diagnostic::do_not_recommend)] +// SAFETY: Safe by the requirements on implementation of [`SimpleOwnableRefCounted`]. +unsafe impl <T :SimpleOwnableRefCounted >Ownable for T { +unsafe fn release (this:NonNull <Self >) { +// SAFETY: Safe by the requirements on implementation of +// [`SimpleOwnableRefCounted::dec_ref()`]. +unsafe {SimpleOwnableRefCounted ::dec_ref (this) }; + } +} + +#[cfg_attr( RUSTC_HAS_DO_NOT_RECOMMEND , diagnostic::do_not_recommend)] +// SAFETY: Safe by the requirements on implementation of [`SimpleOwnableRefCounted`]. +unsafe impl <T :SimpleOwnableRefCounted >RefCounted for T { +fn inc_ref (&self) { +SimpleOwnableRefCounted ::inc_ref (self); + } + +unsafe fn dec_ref (this:NonNull <Self >) { +// SAFETY: Safe by the requirements on implementation of +// [`SimpleOwnableRefCounted::dec_ref()`]. +unsafe {SimpleOwnableRefCounted ::dec_ref (this) }; + } +} + +impl <T :OwnableRefCounted >TryFrom <ARef <T >>for Owned <T > { +type Error =ARef <T >; +/// Tries to convert the [`ARef`] to an [`Owned`] by calling +/// [`try_from_shared()`](OwnableRefCounted::try_from_shared). In case the [`ARef`] is not +/// unique, it returns again an [`ARef`] to the same underlying object. +fn try_from (b:ARef <T >) ->Result <Owned <T >,Self ::Error > { +T ::try_from_shared (b) + } +} +/// A sum type that always holds either a value of type `L` or `R`. /// /// # Examples
Signature · 1 line
2.48.1