rust: add `Ownable` trait and `Owned` type
Subsystems (28)
Andreas Hindborg
maintainerv22 cover rust: add `Ownable` trait and `Owned` type
Add a new trait Ownable and type Owned for types that specify their own way of performing allocation and destruction. This is useful for types from the C side.
At most one Owned<T> exists for an object at any time. The type T decides whether other references to the object, such as an ARef<T>, may exist together with the Owned<T>.
Implement ForeignOwnable for Owned.
Split the RefCounted trait out of AlwaysRefCounted, so that a type can be used with ARef without allowing the &T -> ARef<T> conversion.
Add the traits OwnableIntoShared and OwnableTryFromShared that allow conversion between Owned and ARef. This is analogous to conversion between UniqueArc and Arc. The two conversions are provided by separate traits, as some types cannot become unique again after having been shared.
Patches 1-3 implement Ownable and can be merged on their own.
Patch 4 splits the RefCounted trait out of AlwaysRefCounted.
Patch 5 adds Owned <-> ARef interop via OwnableIntoShared and OwnableTryFromShared.
---
Changes in v22:
- Rebase on v7.4-rc2.
- Split OwnableRefCounted into OwnableIntoShared and OwnableTryFromShared, so that a type can provide one conversion without the other (Alice).
- Rework the safety requirements of Ownable and Owned. An Owned<T> is now unique among Owned<T> handles, and T decides whether other references may exist together with it. Document this in a new "Access model" section on Ownable (Alice).
- Allow AlwaysRefCounted to be implemented together with Ownable for types that allow an ARef<T> to exist together with an Owned<T> (Alice).
- Justify AlwaysRefCounted implementations by all instances of the type being reference counted, rather than by the type not implementing Ownable (Alice, Gary).
- Update the safety comments of the ForeignOwnable implementation for Owned and the conversion trait documentation for the reworked invariants.
- Split RefCounted out of AlwaysRefCounted for the fwctl and serdev Device types (Sashiko).
- Split RefCounted out of AlwaysRefCounted for Fence, which is new in v7.4-rc1.
- Relax the ForeignOwnable implementation for ARef<T> to require T: RefCounted rather than T: AlwaysRefCounted (Sashiko).
- Move the documentation updates for Ownable and Owned from the OwnableRefCounted patch to the patch that adds the types (Alice).
- Remove the empty line after the hidden imports in the examples (Alice).
- Document the type invariant of Foo in the Ownable example.
- Drop Reviewed-by tags from the patches adding Ownable/Owned and ForeignOwnable for Owned, and from the RefCounted rename patch, as their safety requirements changed.
- Move Page changes to their own series to be submitted separately.
- Drop the patch adding SAFETY documentation for the ARef example, it will be submitted separately.
- Link to v21: https://msgid.link/[email protected]
Changes in v21:
- Require callers of Owned::from_raw() to treat the pointee as pinned (Sashiko).
- Import Page directly in allocator.rs instead of using the page::Page path (Danilo).
- Update DRM GPUVM for the RefCounted/AlwaysRefCounted split (Sashiko).
- Rework the SAFETY comments in the ARef::into_raw doctest to justify the correct obligations (Sashiko).
- Use sync::Refcount in the OwnableRefCounted example (Gary, Danilo).
- Add a link to the SAFETY TODO tracking issue to the ARef example patch (Miguel).
- Convert Page to AlwaysRefCounted backed by get_page() and put_page() instead of Ownable, and return ARef<Page> from Page::alloc_page() (Alice).
- Update Rust Binder to store ARef<Page> instead of Owned<Page> (Alice).
- Add ExclusivePage as the in-tree Owned user, without Deref<Target = Page> as that would break its aliasing invariant. The type was previously posted as SafePage and is renamed here (Alice).
- Reorder the series to keep the Page patches together at the end.
- Link to v20: https://msgid.link/[email protected]
Changes in v20:
- Fix a few copy/paste errors in safety comments (Sashiko).
- Use self.page.get() rather than Opaque::cast_into (Alice).
- Add a space between generics in a comment (Sashiko).
- Change a safety comment to reference Box rather than KBox (Sashiko).
- Link to v19: https://msgid.link/[email protected]
Changes in v19:
- Update workqueue.rs and the aref module docs to use RefCounted instead of AlwaysRefCounted (Sashiko).
- Remove the default OwnableRefCounted::into_shared implementation to keep the trait safe (Sashiko).
- Fix the ARef<Self> rustdoc link (Sashiko).
- Reuse Owned::into_raw/from_raw in the ForeignOwnable implementation (Gary).
- Link to v18: https://msgid.link/[email protected]
Changes in v18:
- Rebase on rust-next (2026-06-24).
- Drop the 'static bound on ForeignOwnable for Owned (Gary).
- Make Ownable::release take a raw pointer instead of &mut self (Alice, Sashiko).
- Drop types::ARef re-export (Alice).
- Drop unneeded #[repr(transparent)] on Owned (Gary).
- Fix FOREIGN_ALIGN for Owned to report the pointee alignment (Sashiko).
- Remove BorrowedPage; use &Page directly (Alice).
- Update Rust Binder for the Owned<Page> conversion (Alice).
- Update pwm.rs for the RefCounted/AlwaysRefCounted split (Sashiko).
- Fix documentation nits: missing // INVARIANT: comments, stale Page docs, and a stray mut (Sashiko).
- Expand the use statements touched by the rename patch to the multi-line style (Onur).
- Link to v17: https://msgid.link/[email protected]
Changes in v17:
- Rebase on v7.1-rc2.
- Reorder patches so that Ownable can merge without OwnableRefCounted (Alice).
- Add #[inline] directives to short functions added by the series (Gary).
- Link to v16: https://msgid.link/[email protected]
Changes in v16:
- Simplify pointer to reference cast in Page::from_raw.
- Use NonNull<Page> rather than Owned<Page> for BorrowedPage internals.
- Use "convertible to reference" wording when converting pointers to references.
- Fix formatting for Page::from_raw docs.
- Leave imports alone when adding safety comment to aref example.
- Use KBox::into_nonnull for examples.
- Add patch for KBox::into_nonnull.
- Change invariants and safety comments of Ownable and make the trait safe.
- Make Ownable::release take a mutable reference.
- Fix error handling in example for Ownable
- Link to v15: https://msgid.link/[email protected]
Changes in v15:
- Update series with original SoB's.
- Rename AlwaysRefCounted in kernel::usb.
- Rename Owned::get_pin_mut to Owned::as_pin_mut.
- Link to v14: https://msgid.link/[email protected]
Changes in v14:
- Rebase on v6.19-rc7.
- Rewrite cover letter.
- Update documentation and safety comments based on v13 feedback.
- Update commit messages.
- Reorder implementation blocks in owned.rs.
- Update example in owned.rs to use try operator rather than expect.
- Reformat use statements.
- Add patch: rust: page: convert to Ownable.
- Add patch: rust: implement ForeignOwnable for Owned.
- Add patch: rust: page: add from_raw().
- Link to v13: https://lore.kernel.org/r/[email protected]
Changes in v13:
- Rebase onto v6.18-rc1 (Andreas's work).
- Documentation and style fixes contributed by Andreas
- Link to v12: https://lore.kernel.org/r/[email protected]
Changes in v12:
-
- Rebase onto v6.17-rc1 (Andreas's work).
- moved kernel/types/ownable.rs to kernel/owned.rs
- Drop OwnableMut, make DerefMut depend on Unpin instead. I understood ML discussion as that being okay, but probably needs further scrunity.
- Lots of more documentation changes suggested by reviewers.
- Usage example for Ownable/Owned.
- Link to v11: https://lore.kernel.org/r/[email protected]
Changes in v11:
- Rework of documentation. I tried to honor all requests for changes "in spirit" plus some clearifications and corrections of my own.
- Dropping SimpleOwnedRefCounted by request from Alice, as it creates a potentially problematic blanket implementation (which a derive macro that could be created later would not have).
- Dropping Miguel's "kbuild: provide RUSTC_HAS_DO_NOT_RECOMMEND symbol" patch, as it is not needed anymore after dropping SimpleOwnedRefCounted. (I can add it again, if it is considered useful anyway).
- Link to v10: https://lore.kernel.org/r/[email protected]
Changes in v10:
- Moved kernel/ownable.rs to kernel/types/ownable.rs
- Fixes in documentation / comments as suggested by Andreas Hindborg
- Added Reviewed-by comment for Andreas Hindborg
- Fix rustfmt of pid_namespace.rs
- Link to v9: https://lore.kernel.org/r/[email protected]
Changes in v9:
- Rebase onto v6.14-rc7
- Move Ownable/OwnedRefCounted/Ownable, etc., into separate module
- Documentation fixes to Ownable/OwnableMut/OwnableRefCounted
- Add missing SAFETY documentation to ARef example
- Link to v8: https://lore.kernel.org/r/[email protected]
Changes in v8:
- Fix Co-developed-by and Suggested-by tags as suggested by Miguel and Boqun
- Some small documentation fixes in Owned/Ownable patch
- removing redundant trait constraint on DerefMut for Owned as suggested by Boqun Feng
- make SimpleOwnedRefCounted no longer implement RefCounted as suggested by Boqun Feng
- documentation for RefCounted as suggested by Boqun Feng
- Link to v7: https://lore.kernel.org/r/[email protected]
Changes in v7:
- Squash patch to make Owned::from_raw/into_raw public into parent
- Added Signed-off-by to other people's commits
- Link to v6: https://lore.kernel.org/r/[email protected]
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
To: Danilo Krummrich <[email protected]>
To: Lorenzo Stoakes <[email protected]>
To: Vlastimil Babka <[email protected]>
To: "Liam R. Howlett" <[email protected]>
To: Uladzislau Rezki <[email protected]>
To: Miguel Ojeda <[email protected]>
To: Boqun Feng <[email protected]>
To: Gary Guo <[email protected]>
To: Björn Roy Baron <[email protected]>
To: Benno Lossin <[email protected]>
To: Andreas Hindborg <[email protected]>
To: Alice Ryhl <[email protected]>
To: Trevor Gross <[email protected]>
To: Daniel Almeida <[email protected]>
To: Tamir Duberstein <[email protected]>
To: Alexandre Courbot <[email protected]>
To: Onur Özkan <[email protected]>
To: Lyude Paul <[email protected]>
To: Greg Kroah-Hartman <[email protected]>
To: Christian Brauner <[email protected]>
To: "Rafael J. Wysocki" <[email protected]>
To: Dave Ertman <[email protected]>
To: Ira Weiny <[email protected]>
To: Leon Romanovsky <[email protected]>
To: Paul Moore <[email protected]>
To: Serge Hallyn <[email protected]>
To: David Airlie <[email protected]>
To: Simona Vetter <[email protected]>
To: Alexander Viro <[email protected]>
To: Jan Kara <[email protected]>
To: Igor Korotin <[email protected]>
To: Viresh Kumar <[email protected]>
To: Nishanth Menon <[email protected]>
To: Stephen Boyd <[email protected]>
To: Bjorn Helgaas <[email protected]>
To: Krzysztof Wilczyński <[email protected]>
To: Pavel Tikhomirov <[email protected]>
To: Michal Wilczynski <[email protected]>
To: Ira Weiny <[email protected]>
To: Matthew Brost <[email protected]>
To: Thomas Hellström <[email protected]>
To: Johan Hovold <[email protected]>
To: Sumit Semwal <[email protected]>
To: Christian König <[email protected]>
To: Dave Jiang <[email protected]>
To: Jason Gunthorpe <[email protected]>
To: Saeed Mahameed <[email protected]>
To: Zhi Wang <[email protected]>
To: Jonathan Cameron <[email protected]>
To: Markus Probst <[email protected]>
Cc: Philipp Stanner <[email protected]>
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
---
Andreas Hindborg (2):
rust: alloc: add KBox::into_non_null
rust: implement ForeignOwnable for Owned
Asahi Lina (1):
rust: types: Add Ownable/Owned types
Oliver Mangold (2):
rust: rename AlwaysRefCounted to RefCounted
rust: Add OwnableIntoShared and OwnableTryFromShared
rust/kernel/alloc/kbox.rs | 9 + rust/kernel/auxiliary.rs | 10 +- rust/kernel/block/mq/request.rs | 17 +- rust/kernel/cred.rs | 16 +- rust/kernel/device.rs | 12 +- rust/kernel/device/property.rs | 11 +- rust/kernel/dma_buf/dma_fence.rs | 9 +- rust/kernel/drm/device.rs | 9 +- rust/kernel/drm/gem/mod.rs | 16 +- rust/kernel/drm/gpuvm/mod.rs | 9 +- rust/kernel/drm/gpuvm/vm_bo.rs | 6 +- rust/kernel/fs/file.rs | 23 +- rust/kernel/fwctl.rs | 9 +- rust/kernel/i2c.rs | 13 +- rust/kernel/lib.rs | 1 + rust/kernel/mm.rs | 23 +- rust/kernel/mm/mmput_async.rs | 12 +- rust/kernel/opp.rs | 16 +- rust/kernel/owned.rs | 494 +++++++++++++++++++++++++++++++++++++++ rust/kernel/pci.rs | 10 +- rust/kernel/pid_namespace.rs | 15 +- rust/kernel/platform.rs | 10 +- rust/kernel/pwm.rs | 12 +- rust/kernel/serdev.rs | 11 +- rust/kernel/sync/aref.rs | 82 +++++-- rust/kernel/task.rs | 13 +- rust/kernel/types.rs | 13 ++ rust/kernel/usb.rs | 17 +- rust/kernel/workqueue.rs | 8 +- 29 files changed, 823 insertions(+), 83 deletions(-)
---
base-commit: 7475ea8b58616b33c04afb976cf0fbaad9dd63fb
change-id: 20250305-unique-ref-29fcd675f9e9
Best regards,
Signature · 1 line
Andreas Hindborg <[email protected]>
Andreas Hindborg
maintainerPATCH v22 1/5 rust: alloc: add `KBox::into_non_null`
Add a method to consume a Box<T, A> and return a NonNull<T>. This is a convenience wrapper around Self::into_raw for callers that need a NonNull pointer rather than a raw pointer.
--- rust/kernel/alloc/kbox.rs | 9 +++++++++ 1 file changed, 9 insertions(+)
rust/kernel/alloc/kbox.rs +9 -0
@@ -211,6 +211,15 @@ pub fn leak<'a>(b: Self) -> &'a mut T {// which points to an initialized instance of `T`. unsafe { &mut *Box ::into_raw (b) } } + +/// Consumes the `Box<T, A>` and returns a `NonNull<T>`. +/// +/// Like [`Self::into_raw`], but returns a `NonNull`. +#[inline] +pub fn into_non_null (b:Self ) ->NonNull <T > { +// SAFETY: `Box::into_raw` returns a valid pointer. +unsafe {NonNull ::new_unchecked (Self ::into_raw (b)) } + } }impl <T ,A >Box <MaybeUninit <T >,A >
Signature · 1 line
2.54.0
[email protected]
AI reviewRe: [PATCH v22 1/5] rust: alloc: add `KBox::into_non_null`
Sashiko has reviewed this patch and found no issues.
Quoted 5 lines
Add a method to consume a
Box<T, A>and return aNonNull<T>. This is a convenience wrapper aroundSelf::into_rawfor callers that need aNonNullpointer rather than a raw pointer.Signed-off-by Andreas Hindborg <[email protected]>
Sashiko has reviewed this patch and found no issues.
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1
Andreas Hindborg
maintainerPATCH v22 2/5 rust: types: Add Ownable/Owned types
In reply to Andreas HindborgFrom: 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 an ARef<T>, an Owned<T> cannot be cloned. At most one Owned<T> exists for an object at any time, and the type T decides whether other references to the object may exist together with it.
Conceptually, this is similar to a KBox<T>, except that it delegates resource management to the T instead of using a generic allocator.
[ om:
- Split code into separate file and pub use it from types.rs.
- Make from_raw() and into_raw() public.
- Remove OwnableMut, and make DerefMut dependent on Unpin instead.
- Usage example/doctest for Ownable/Owned.
- Fixes to documentation and commit message.
]
[ Andreas: Updated documentation, examples, and formatting. Change safety
requirements, safety comments. Let T decide whether other references may exist together with an Owned<T>. ]
--- rust/kernel/lib.rs | 1 + rust/kernel/owned.rs | 274 +++++++++++++++++++++++++++++++++++++++++++++++ rust/kernel/sync/aref.rs | 5 + rust/kernel/types.rs | 5 + 4 files changed, 285 insertions(+)
rust/kernel/lib.rs +1 -0
@@ -111,6 +111,7 @@pub mod of;#[cfg( CONFIG_PM_OPP )] pub mod opp; +pub mod owned;pub mod page;#[cfg( CONFIG_PCI )] pub mod pci;
rust/kernel/owned.rs new file +274 -0
274 lines not on this page · raw message
rust/kernel/sync/aref.rs +5 -0
@@ -39,6 +39,11 @@/// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted /// instances of a type. /// +/// Note: Implementing this trait allows types to be wrapped in an [`ARef<Self>`]. It requires an +/// internal reference count and provides only shared references. If unique references are required +/// [`Ownable`](crate::types::Ownable) should be implemented which allows types to be wrapped in an +/// [`Owned<Self>`](crate::types::Owned). +/// /// # Safety /// /// Implementers must ensure that increments to the reference count keep the object alive in memory
rust/kernel/types.rs +5 -0
@@ -18,6 +18,11 @@ ForLt, // }; +pub use crate ::owned::{ +Ownable , +Owned ,// +}; +/// Used to transfer ownership to and from foreign (non-Rust) languages. /// /// Ownership is transferred from Rust to a foreign language by calling [`Self::into_foreign`] and
Signature · 1 line
2.54.0
[email protected]
AI reviewRe: [PATCH v22 2/5] rust: types: Add Ownable/Owned types
Sashiko has reviewed this patch and found no issues.
Quoted 23 lines
From: Asahi Lina <[email protected]>
By analogy to
AlwaysRefCountedandARef, anOwnabletype is a (typically C FFI) type that *may* be owned by Rust, but need not be. Unlike anARef<T>, anOwned<T>cannot be cloned. At most oneOwned<T>exists for an object at any time, and the typeTdecides whether other references to the object may exist together with it.Conceptually, this is similar to a
KBox<T>, except that it delegates resource management to theTinstead of using a generic allocator.[ om:
- Split code into separate file andpub useit fromtypes.rs.
- Makefrom_raw()andinto_raw()public.
- Remove OwnableMut, and make DerefMut dependent on Unpin instead.
- Usage example/doctest for Ownable/Owned.
- Fixes to documentation and commit message.
]Signed-off-by Asahi Lina <[email protected]>Co-developed-by Oliver Mangold <[email protected]>Signed-off-by Oliver Mangold <[email protected]>
Quoted 5 lines
[ Andreas: Updated documentation, examples, and formatting. Change safety
requirements, safety comments. LetTdecide whether other references may exist together with anOwned<T>. ]Co-developed-by Andreas Hindborg <[email protected]>Signed-off-by Andreas Hindborg <[email protected]>
Sashiko has reviewed this patch and found no issues.
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=2
Andreas Hindborg
maintainerPATCH v22 3/5 rust: implement `ForeignOwnable` for `Owned`
In reply to Andreas HindborgImplement ForeignOwnable for Owned<T>. This allows use of Owned<T> in places such as the XArray.
Note that T does not need to implement ForeignOwnable for Owned<T> to implement ForeignOwnable.
--- rust/kernel/owned.rs | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+)
rust/kernel/owned.rs +57 -0
@@ -15,6 +15,8 @@ ptr::NonNull, // }; +use kernel::types::ForeignOwnable ; +/// Types that specify their own way of performing allocation and destruction. Typically, this trait /// is implemented on types from the C side. ///
@@ -272,3 +274,58 @@ fn drop(&mut self) {unsafe {T ::release (self.ptr) }; } } + +// SAFETY: We derive the pointer to `T` from a valid `T`, so the returned +// pointer satisfy alignment requirements of `T`. +unsafe impl <T :Ownable >ForeignOwnable for Owned <T > { +const FOREIGN_ALIGN :usize = core::mem::align_of ::<T >(); + +type Borrowed <'a> + = &'aT +where +Self : 'a; +type BorrowedMut <'a> + =Pin <&'amut T > +where +Self : 'a; + +#[inline] +fn into_foreign (self) -> *mut kernel::ffi::c_void { +Owned ::into_raw (self).as_ptr ().cast () + } + +#[inline] +unsafe fn from_foreign (ptr: *mut kernel::ffi::c_void ) ->Self { +// SAFETY: By function safety contract, `ptr` came from `into_foreign` and cannot be null. +let ptr =unsafe {NonNull ::new_unchecked (ptr.cast ()) }; + +// SAFETY: By the function safety contract, `ptr` was returned by `into_foreign`, which +// consumed an `Owned<T>` without calling `T::release`. The requirements that were upheld +// for that `Owned<T>` are still upheld, as the ownership it represented was only held by +// the foreign pointer in the meantime. We retake that ownership here. +unsafe {Owned ::from_raw (ptr) } + } + +#[inline] +unsafe fn borrow <'a>(ptr: *mut kernel::ffi::c_void ) ->Self ::Borrowed <'a> { +// SAFETY: By function safety requirements, `ptr` came from `into_foreign` and the +// `Owned<T>` it was created from is not reconstructed or mutably borrowed during `'a`. By +// the type invariants of that `Owned<T>`, `ptr` points to a valid `T` and it is sound to +// create a shared reference to the `T` for `'a`. +unsafe { &*ptr.cast () } + } + +#[inline] +unsafe fn borrow_mut <'a>(ptr: *mut kernel::ffi::c_void ) ->Self ::BorrowedMut <'a> { +// SAFETY: By function safety requirements, `ptr` came from `into_foreign` and the +// `Owned<T>` it was created from is not reconstructed or otherwise borrowed during `'a`. By +// the type invariants of that `Owned<T>`, `ptr` points to a valid `T` and it is sound to +// create a mutable reference to the `T` for `'a`, given that we only hand it out as a +// `Pin<&mut T>` below. +let inner =unsafe { &mut *ptr.cast () }; + +// SAFETY: We never move out of inner, and we do not hand out mutable +// references when `T: !Unpin`. +unsafe {Pin ::new_unchecked (inner) } + } +}
Signature · 1 line
2.54.0
[email protected]
AI reviewRe: [PATCH v22 3/5] rust: implement `ForeignOwnable` for `Owned`
Sashiko has reviewed this patch and found no issues.
Quoted 7 lines
Implement
ForeignOwnableforOwned<T>. This allows use ofOwned<T>in places such as theXArray.Note that
Tdoes not need to implementForeignOwnableforOwned<T>to implementForeignOwnable.Signed-off-by Andreas Hindborg <[email protected]>
Sashiko has reviewed this patch and found no issues.
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=3
Andreas Hindborg
maintainerPATCH v22 4/5 rust: rename `AlwaysRefCounted` to `RefCounted`
In reply to Andreas HindborgFrom: Oliver Mangold <[email protected]>
There are types where it may both be reference counted in some cases and owned in others. For such types, obtaining an ARef<T> from a &T may be unsound, as it allows creation of an ARef<T> from a &Owned<T>.
Therefore, we split AlwaysRefCounted into RefCounted (which ARef<T> would require) and a marker trait to indicate that the &T -> ARef<T> conversion is sound for the type. A type that implements Ownable may only implement the marker trait if it allows an ARef<T> to exist together with an Owned<T>.
- Rename AlwaysRefCounted to RefCounted.
- Add a new unsafe trait AlwaysRefCounted.
- Implement the new trait AlwaysRefCounted for the newly renamed RefCounted implementations. This leaves functionality of existing implementers of AlwaysRefCounted intact.
[ Andreas: Updated commit message, rebased on v7.4-rc2, converted new
implementers, relaxed the ForeignOwnable bound for ARef<T>, updated safety comments. ]
--- rust/kernel/auxiliary.rs | 10 ++++++- rust/kernel/block/mq/request.rs | 17 +++++++---- rust/kernel/cred.rs | 16 ++++++++-- rust/kernel/device.rs | 12 ++++++-- rust/kernel/device/property.rs | 11 +++++-- rust/kernel/dma_buf/dma_fence.rs | 9 ++++-- rust/kernel/drm/device.rs | 9 ++++-- rust/kernel/drm/gem/mod.rs | 16 +++++++--- rust/kernel/drm/gpuvm/mod.rs | 9 ++++-- rust/kernel/drm/gpuvm/vm_bo.rs | 6 +++- rust/kernel/fs/file.rs | 23 ++++++++++++--- rust/kernel/fwctl.rs | 9 ++++-- rust/kernel/i2c.rs | 13 +++++++-- rust/kernel/mm.rs | 23 ++++++++++++--- rust/kernel/mm/mmput_async.rs | 12 ++++++-- rust/kernel/opp.rs | 16 ++++++++-- rust/kernel/owned.rs | 2 +- rust/kernel/pci.rs | 10 ++++++- rust/kernel/pid_namespace.rs | 15 ++++++++-- rust/kernel/platform.rs | 10 ++++++- rust/kernel/pwm.rs | 12 ++++++-- rust/kernel/serdev.rs | 11 +++++-- rust/kernel/sync/aref.rs | 63 +++++++++++++++++++++++++--------------- rust/kernel/task.rs | 13 +++++++-- rust/kernel/types.rs | 12 ++++++-- rust/kernel/usb.rs | 17 +++++++++-- rust/kernel/workqueue.rs | 8 ++--- 27 files changed, 297 insertions(+), 87 deletions(-)
rust/kernel/auxiliary.rs +9 -1
@@ -19,6 +19,10 @@ to_result, // }, prelude::*, + sync::aref::{ + AlwaysRefCounted, + RefCounted, // + }, types::{CovariantForLt ,ForLt ,
@@ -389,7 +393,7 @@ unsafe impl<Ctx: device::DeviceContext> device::AsBusDevice<Ctx> for Device<Ctx> kernel::impl_device_context_into_aref!(Device );// SAFETY: Instances of `Device` are always reference-counted. -unsafe impl crate ::sync::aref::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_ref ().as_raw ()) };
@@ -408,6 +412,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount +// is non-zero and it is okay to obtain an `ARef<Device>` from it. +unsafe impl AlwaysRefCounted for Device {} +impl <Ctx : device::DeviceContext >AsRef <device::Device <Ctx >>for Device <Ctx > {fn as_ref (&self) -> &device::Device <Ctx > {// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
rust/kernel/block/mq/request.rs +11 -6
@@ -11,7 +11,8 @@ sync::{ aref::{ARef , - AlwaysRefCounted, // +AlwaysRefCounted , +RefCounted ,// }, atomic::Relaxed, Refcount, //
@@ -235,11 +236,10 @@ unsafe impl<T: Operations> Send for Request<T> {}// mutate `self` are internally synchronized` 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 -// keeps the object alive in memory at least until a matching reference count -// decrement is executed. -unsafe impl <T :Operations >AlwaysRefCounted for Request <T > { +// SAFETY: All instances of `Request<T>` are reference counted. This 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 >RefCounted for Request <T > {fn inc_ref (&self) { self.wrapper_ref ().refcount ().inc (); }
@@ -261,3 +261,8 @@ unsafe fn dec_ref(obj: core::ptr::NonNull<Self>) { } } } + +// SAFETY: All instances of `Request<T>` are currently reference counted, so a `&Request<T>` proves +// that the refcount is non-zero and it is okay to obtain an `ARef<Request<T>>` from it (but this +// will change in the future). +unsafe impl <T :Operations >AlwaysRefCounted for Request <T > {}
rust/kernel/cred.rs +14 -2
@@ -8,7 +8,15 @@//! //! Reference: <https://www.kernel.org/doc/html/latest/security/credentials.html> -use crate ::{bindings, sync::aref::AlwaysRefCounted , task::Kuid , types::Opaque }; +use crate ::{ + bindings, + sync::aref::RefCounted , + task::Kuid , + types::{ +AlwaysRefCounted , +Opaque ,// + },// +};/// Wraps the kernel's `struct cred`. ///
@@ -76,7 +84,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 {#[inline] fn inc_ref (&self) {// SAFETY: The existence of a shared reference means that the refcount is nonzero.
@@ -90,3 +98,7 @@ unsafe fn dec_ref(obj: core::ptr::NonNull<Credential>) {unsafe { bindings::put_cred (obj.cast ().as_ptr ()) }; } } + +// SAFETY: All instances of `Credential` are reference counted, so a `&Credential` proves that the +// refcount is non-zero and it is okay to obtain an `ARef<Credential>` from it. +unsafe impl AlwaysRefCounted for Credential {}
rust/kernel/device.rs +10 -2
@@ -8,8 +8,12 @@ bindings, fmt, prelude::*, - sync::aref::ARef, + sync::aref::{ + ARef, + RefCounted, // + }, types::{ +AlwaysRefCounted ,ForeignOwnable ,Opaque ,// }, //
@@ -435,7 +439,7 @@ pub fn name(&self) -> &CStr { kernel::impl_device_context_into_aref!(Device );// SAFETY: Instances of `Device` are always reference-counted. -unsafe impl crate ::sync::aref::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 ()) };
@@ -447,6 +451,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<Self>) { } } +// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount +// is non-zero and it is okay to obtain an `ARef<Device>` from it. +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/device/property.rs +9 -2
@@ -14,7 +14,10 @@ fmt, prelude::*, str::{CStr, CString}, - sync::aref::ARef, + sync::aref::{ + ARef, + AlwaysRefCounted, // + }, types::Opaque, };
@@ -360,7 +363,7 @@ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { }// SAFETY: Instances of `FwNode` are always reference-counted. -unsafe impl crate ::sync::aref::AlwaysRefCounted for FwNode { +unsafe impl crate ::sync::aref::RefCounted for FwNode {fn inc_ref (&self) {// SAFETY: The existence of a shared reference guarantees that the // refcount is non-zero.
@@ -374,6 +377,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<Self>) { } } +// SAFETY: All instances of `FwNode` are reference counted, so a `&FwNode` proves that the refcount +// is non-zero and it is okay to obtain an `ARef<FwNode>` from it. +unsafe impl AlwaysRefCounted for FwNode {} +enum Node <'a> {Borrowed (&'aFwNode ),Owned (ARef <FwNode >),
rust/kernel/dma_buf/dma_fence.rs +7 -2
@@ -36,7 +36,8 @@ sync::{ aref::{ARef , -AlwaysRefCounted ,// +AlwaysRefCounted , +RefCounted ,// }, atomic::{ Atomic,
@@ -565,7 +566,7 @@ pub unsafe fn from_raw<'a>(ptr: *mut bindings::dma_fence) -> &'a Self {// SAFETY: These implement the C backends refcounting methods which are proven // to work correctly. -unsafe impl AlwaysRefCounted for Fence { +unsafe impl RefCounted for Fence {fn inc_ref (&self) {// SAFETY: `self.as_raw()` is a pointer to a valid `struct dma_fence`. unsafe { bindings::dma_fence_get (self.as_raw ()) }
@@ -582,6 +583,10 @@ unsafe fn dec_ref(ptr: NonNull<Self>) { } } +// SAFETY: All instances of `Fence` are reference counted, so a `&Fence` proves that the refcount is +// non-zero and it is okay to obtain an `ARef<Fence>` from it. +unsafe impl AlwaysRefCounted for Fence {} +// Necessary to guarantee that `inner` always comes first and can be freed by C. // Also useful for using casts instead of container_of(). #[repr( C )]
rust/kernel/drm/device.rs +7 -2
@@ -17,7 +17,8 @@ prelude::*, sync::aref::{ARef , -AlwaysRefCounted ,// +AlwaysRefCounted , +RefCounted ,// }, types::{ NotThreadSafe,
@@ -480,7 +481,7 @@ fn deref(&self) -> &Self::Target {// SAFETY: DRM device objects are always reference counted and the get/put functions // satisfy the requirements. -unsafe impl <T : drm::Driver >AlwaysRefCounted for Device <T > { +unsafe impl <T : drm::Driver >RefCounted for Device <T > {fn inc_ref (&self) {// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero. unsafe { bindings::drm_dev_get (self.as_raw ()) };
@@ -495,6 +496,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount +// is non-zero and it is okay to obtain an `ARef<Device>` from it. +unsafe impl <T : drm::Driver >AlwaysRefCounted for Device <T > {} +impl <T : drm::Driver >AsRef <T ::ParentDevice <device::Normal >>for Device <T > {fn as_ref (&self) -> &T ::ParentDevice <device::Normal > {// SAFETY: `bindings::drm_device::dev` is valid as long as the DRM device itself is valid,
rust/kernel/drm/gem/mod.rs +12 -4
@@ -21,7 +21,7 @@ prelude::*, sync::aref::{ ARef, - AlwaysRefCounted, // + RefCounted, // }, types::Opaque, };
@@ -34,7 +34,7 @@#[cfg( CONFIG_RUST_DRM_GEM_SHMEM_HELPER )] pub mod shmem; -/// A macro for implementing [`AlwaysRefCounted`] for any GEM object type. +/// A macro for implementing [`RefCounted`] for any GEM object type. /// /// Since all GEM objects use the same refcounting scheme. #[macro_export]
@@ -47,7 +47,7 @@ impl $( <$( $tparam_id:ident ),+> )? for $type:ty )? ) => {// SAFETY: All GEM objects are refcounted. - unsafe impl $( <$( $tparam_id ),+> )? $crate::sync::aref::AlwaysRefCounted for $type + unsafe impl $( <$( $tparam_id ),+> )? $crate::sync::aref::RefCounted for $type where Self: IntoGEMObject, $( $( $bind_param : $bind_trait ),+ )?
@@ -66,6 +66,14 @@ unsafe fn dec_ref(obj: core::ptr::NonNull<Self>) {unsafe { bindings::drm_gem_object_put (obj) }; } } + +// SAFETY: All instances of `$type` are reference counted, so a `&$type` proves that the +// refcount is non-zero and it is okay to obtain an `ARef<$type>` from it. + unsafe impl $( <$( $tparam_id ),+> )? $crate::sync::aref::AlwaysRefCounted for $type + where + Self: IntoGEMObject, + $( $( $bind_param : $bind_trait ),+ )? + {} }; } #[cfg_attr(not(CONFIG_RUST_DRM_GEM_SHMEM_HELPER), allow(unused))]
@@ -197,7 +205,7 @@ fn create_handle<D, F>(&self, file: &drm::File<F>) -> Result<u32>/// Looks up an object by its handle for a given `File`. fn lookup_handle <D ,F >(file: &drm::File <F >, handle:u32 ) ->Result <ARef <Self >>where -Self :AllocImpl <Driver =D > +AlwaysRefCounted , +Self :AllocImpl <Driver =D > +RefCounted ,D : drm::Driver <Object =Self ,File =F >,F : drm::file::DriverFile <Driver =D >, {
rust/kernel/drm/gpuvm/mod.rs +7 -2
@@ -22,7 +22,8 @@ prelude::*, sync::aref::{ARef , - AlwaysRefCounted, // +AlwaysRefCounted , +RefCounted ,// }, types::Opaque, // };
@@ -81,7 +82,7 @@ unsafe impl<T: DriverGpuVm> Send for GpuVm<T> {}unsafe impl <T :DriverGpuVm >Sync for GpuVm <T > {}// SAFETY: By type invariants, the allocation is managed by the refcount in `self.vm`. -unsafe impl <T :DriverGpuVm >AlwaysRefCounted for GpuVm <T > { +unsafe impl <T :DriverGpuVm >RefCounted for GpuVm <T > {fn inc_ref (&self) {// SAFETY: By type invariants, the allocation is managed by the refcount in `self.vm`. unsafe { bindings::drm_gpuvm_get (self.vm.get ()) };
@@ -93,6 +94,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `GpuVm<T>` are reference counted, so a `&GpuVm<T>` proves that the +// refcount is non-zero and it is okay to obtain an `ARef<GpuVm<T>>` from it. +unsafe impl <T :DriverGpuVm >AlwaysRefCounted for GpuVm <T > {} +impl <T :DriverGpuVm >PartialEq for GpuVm <T > {#[inline] fn eq (&self, other: &Self ) ->bool {
rust/kernel/drm/gpuvm/vm_bo.rs +5 -1
@@ -29,7 +29,7 @@ unsafe impl<T: DriverGpuVm> Send for GpuVmBo<T> {}unsafe impl <T :DriverGpuVm >Sync for GpuVmBo <T > {}// SAFETY: By type invariants, the allocation is managed by the refcount in `self.inner`. -unsafe impl <T :DriverGpuVm >AlwaysRefCounted for GpuVmBo <T > { +unsafe impl <T :DriverGpuVm >RefCounted for GpuVmBo <T > {fn inc_ref (&self) {// SAFETY: By type invariants, the allocation is managed by the refcount in `self.inner`. unsafe { bindings::drm_gpuvm_bo_get (self.inner.get ()) };
@@ -44,6 +44,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `GpuVmBo<T>` are reference counted, so a `&GpuVmBo<T>` proves that the +// refcount is non-zero and it is okay to obtain an `ARef<GpuVmBo<T>>` from it. +unsafe impl <T :DriverGpuVm >AlwaysRefCounted for GpuVmBo <T > {} +impl <T :DriverGpuVm >PartialEq for GpuVmBo <T > {#[inline] fn eq (&self, other: &Self ) ->bool {
rust/kernel/fs/file.rs +19 -4
@@ -12,8 +12,15 @@ cred::Credential, error::{code::*, to_result, Error, Result}, fmt, - sync::aref::{ARef, AlwaysRefCounted}, - types::{NotThreadSafe, Opaque}, + sync::aref::{ + ARef, + RefCounted, // + }, + types::{ +AlwaysRefCounted , +NotThreadSafe , +Opaque ,// + }, // };use core::ptr;
@@ -197,7 +204,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.
@@ -212,6 +219,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<File>) { } } +// SAFETY: All instances of `File` are reference counted, so a `&File` proves that the refcount is +// non-zero and it is okay to obtain an `ARef<File>` from it. +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.
@@ -233,7 +244,7 @@ pub struct LocalFile {// SAFETY: The type invariants guarantee that `LocalFile` is always ref-counted. This implementation // makes `ARef<LocalFile>` 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.
@@ -249,6 +260,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<LocalFile>) { } } +// SAFETY: All instances of `LocalFile` are reference counted, so a `&LocalFile` proves that the +// refcount is non-zero and it is okay to obtain an `ARef<LocalFile>` from it. +unsafe impl AlwaysRefCounted for LocalFile {} +impl LocalFile {/// Constructs a new `struct file` wrapper from a file descriptor. ///
rust/kernel/fwctl.rs +7 -2
@@ -11,7 +11,8 @@ prelude::*, sync::aref::{ARef , - AlwaysRefCounted, // +AlwaysRefCounted , +RefCounted ,// }, types::Opaque, // };
@@ -259,7 +260,7 @@ fn as_ref(&self) -> &device::Device {// SAFETY: `fwctl_get` increments the refcount of a valid fwctl_device. // `fwctl_put` decrements it and frees the device when it reaches zero. -unsafe impl <T :Operations >AlwaysRefCounted for Device <T > { +unsafe impl <T :Operations >RefCounted for Device <T > {#[inline] fn inc_ref (&self) {// SAFETY: `self` holds a live reference.
@@ -273,6 +274,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `Device<T>` are reference counted, so a `&Device<T>` proves that the +// refcount is non-zero and it is okay to obtain an `ARef<Device<T>>` from it. +unsafe impl <T :Operations >AlwaysRefCounted for Device <T > {} +// SAFETY: `Device<T>` is refcounted by the fwctl core and may be released from any thread. unsafe impl <T :Operations >Send for Device <T > {}
rust/kernel/i2c.rs +10 -3
@@ -17,7 +17,8 @@ prelude::*, sync::aref::{ARef , - AlwaysRefCounted, // +AlwaysRefCounted , +RefCounted ,// }, types::Opaque, // };
@@ -414,7 +415,7 @@ pub fn get(index: i32) -> Result<ARef<Self>> { kernel::impl_device_context_into_aref!(I2cAdapter );// SAFETY: Instances of `I2cAdapter` are always reference-counted. -unsafe impl AlwaysRefCounted for I2cAdapter { +unsafe impl RefCounted for I2cAdapter {#[inline] fn inc_ref (&self) {// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
@@ -427,6 +428,9 @@ unsafe fn dec_ref(obj: NonNull<Self>) {unsafe { bindings::i2c_put_adapter (obj.as_ref ().as_raw ()) } } } +// SAFETY: All instances of `I2cAdapter` are reference counted, so a `&I2cAdapter` proves that the +// refcount is non-zero and it is okay to obtain an `ARef<I2cAdapter>` from it. +unsafe impl AlwaysRefCounted for I2cAdapter {}/// The i2c board info representation ///
@@ -492,7 +496,7 @@ unsafe impl<Ctx: device::DeviceContext> device::AsBusDevice<Ctx> for I2cClient<C kernel::impl_device_context_into_aref!(I2cClient );// SAFETY: Instances of `I2cClient` are always reference-counted. -unsafe impl AlwaysRefCounted for I2cClient { +unsafe impl RefCounted for I2cClient {fn inc_ref (&self) {// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero. unsafe { bindings::get_device (self.as_ref ().as_raw ()) };
@@ -503,6 +507,9 @@ unsafe fn dec_ref(obj: NonNull<Self>) {unsafe { bindings::put_device (&raw mut (*obj.as_ref ().as_raw ()).dev) } } } +// SAFETY: All instances of `I2cClient` are reference counted, so a `&I2cClient` proves that the +// refcount is non-zero and it is okay to obtain an `ARef<I2cClient>` from it. +unsafe impl AlwaysRefCounted for I2cClient {}impl <Ctx : device::DeviceContext >AsRef <device::Device <Ctx >>for I2cClient <Ctx > {fn as_ref (&self) -> &device::Device <Ctx > {
rust/kernel/mm.rs +19 -4
@@ -13,8 +13,15 @@use crate ::{ bindings, - sync::aref::{ARef ,AlwaysRefCounted }, - types::{NotThreadSafe ,Opaque }, + sync::aref::{ +ARef , +RefCounted ,// + }, + types::{ +AlwaysRefCounted , +NotThreadSafe , +Opaque ,// + },// };use core::{ops::Deref , ptr::NonNull };
@@ -55,7 +62,7 @@ unsafe impl Send for Mm {}unsafe impl Sync for Mm {}// SAFETY: By the type invariants, this type is always refcounted. -unsafe impl AlwaysRefCounted for Mm { +unsafe impl RefCounted for Mm {#[inline] fn inc_ref (&self) {// SAFETY: The pointer is valid since self is a reference.
@@ -69,6 +76,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `Mm` are reference counted, so a `&Mm` proves that the refcount is +// non-zero and it is okay to obtain an `ARef<Mm>` from it. +unsafe impl AlwaysRefCounted for Mm {} +/// A wrapper for the kernel's `struct mm_struct`. /// /// This type is like [`Mm`], but with non-zero `mm_users`. It can only be used when `mm_users` can
@@ -91,7 +102,7 @@ unsafe impl Send for MmWithUser {}unsafe impl Sync for MmWithUser {}// SAFETY: By the type invariants, this type is always refcounted. -unsafe impl AlwaysRefCounted for MmWithUser { +unsafe impl RefCounted for MmWithUser {#[inline] fn inc_ref (&self) {// SAFETY: The pointer is valid since self is a reference.
@@ -105,6 +116,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `MmWithUser` are reference counted, so a `&MmWithUser` proves that the +// refcount is non-zero and it is okay to obtain an `ARef<MmWithUser>` from it. +unsafe impl AlwaysRefCounted for MmWithUser {} +// Make all `Mm` methods available on `MmWithUser`. impl Deref for MmWithUser {type Target =Mm ;
rust/kernel/mm/mmput_async.rs +10 -2
@@ -10,7 +10,11 @@use crate ::{ bindings, mm::MmWithUser , - sync::aref::{ARef ,AlwaysRefCounted }, + sync::aref::{ +ARef , +RefCounted ,// + }, + types::AlwaysRefCounted , };use core::{ops::Deref , ptr::NonNull };
@@ -34,7 +38,7 @@ unsafe impl Send for MmWithUserAsync {}unsafe impl Sync for MmWithUserAsync {}// SAFETY: By the type invariants, this type is always refcounted. -unsafe impl AlwaysRefCounted for MmWithUserAsync { +unsafe impl RefCounted for MmWithUserAsync {#[inline] fn inc_ref (&self) {// SAFETY: The pointer is valid since self is a reference.
@@ -48,6 +52,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `MmWithUserAsync` are reference counted, so a `&MmWithUserAsync` proves +// that the refcount is non-zero and it is okay to obtain an `ARef<MmWithUserAsync>` from it. +unsafe impl AlwaysRefCounted for MmWithUserAsync {} +// Make all `MmWithUser` methods available on `MmWithUserAsync`. impl Deref for MmWithUserAsync {type Target =MmWithUser ;
rust/kernel/opp.rs +13 -3
@@ -16,8 +16,14 @@ ffi::{c_char, c_ulong}, prelude::*, str::CString, - sync::aref::{ARef, AlwaysRefCounted}, - types::Opaque, + sync::aref::{ + ARef, + RefCounted, // + }, + types::{ +AlwaysRefCounted , +Opaque ,// + }, // };#[cfg( CONFIG_CPU_FREQ )]
@@ -1041,7 +1047,7 @@ unsafe impl Send for OPP {}unsafe impl Sync for OPP {}/// SAFETY: The type invariants guarantee that [`OPP`] is always refcounted. -unsafe impl AlwaysRefCounted for OPP { +unsafe impl RefCounted for OPP {#[inline] fn inc_ref (&self) {// SAFETY: The existence of a shared reference means that the refcount is nonzero.
@@ -1055,6 +1061,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<Self>) { } } +// SAFETY: All instances of `OPP` are reference counted, so a `&OPP` proves that the refcount is +// non-zero and it is okay to obtain an `ARef<OPP>` from it. +unsafe impl AlwaysRefCounted for OPP {} +impl OPP {/// Creates an owned reference to a [`OPP`] from a valid pointer. ///
rust/kernel/owned.rs +1 -1
@@ -28,7 +28,7 @@/// /// Note: The underlying object is not required to provide internal reference counting, because it /// represents a unique, owned reference. If reference counting (on the Rust side) is required, -/// [`AlwaysRefCounted`](crate::sync::aref::AlwaysRefCounted) should be implemented. +/// [`RefCounted`](crate::types::RefCounted) should be implemented. /// /// # Access model ///
rust/kernel/pci.rs +9 -1
@@ -20,6 +20,10 @@ io::resource, prelude::*, str::CStr, + sync::aref::{ + AlwaysRefCounted, + RefCounted, // + }, types::Opaque, ThisModule, // };
@@ -510,7 +514,7 @@ unsafe impl<Ctx: device::DeviceContext> device::AsBusDevice<Ctx> for Device<Ctx>impl <'a>crate ::dma::Device <'a>for Device <device::Core <'a>> {}// SAFETY: Instances of `Device` are always reference-counted. -unsafe impl crate ::sync::aref::AlwaysRefCounted for Device { +unsafe impl RefCounted for Device {#[inline] fn inc_ref (&self) {// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
@@ -524,6 +528,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount +// is non-zero and it is okay to obtain an `ARef<Device>` from it. +unsafe impl AlwaysRefCounted for Device {} +impl <Ctx : device::DeviceContext >AsRef <device::Device <Ctx >>for Device <Ctx > {fn as_ref (&self) -> &device::Device <Ctx > {// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
rust/kernel/pid_namespace.rs +13 -2
@@ -7,7 +7,14 @@//! C header: [`include/linux/pid_namespace.h`](srctree/include/linux/pid_namespace.h) and //! [`include/linux/pid.h`](srctree/include/linux/pid.h) -use crate ::{bindings, sync::aref::AlwaysRefCounted , types::Opaque }; +use crate ::{ + bindings, + sync::aref::RefCounted , + types::{ +AlwaysRefCounted , +Opaque ,// + },// +};use core::ptr;/// Wraps the kernel's `struct pid_namespace`. Thread safe.
@@ -41,7 +48,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.
@@ -55,6 +62,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<PidNamespace>) { } } +// SAFETY: All instances of `PidNamespace` are reference counted, so a `&PidNamespace` proves that +// the refcount is non-zero and it is okay to obtain an `ARef<PidNamespace>` from it. +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/platform.rs +9 -1
@@ -24,6 +24,10 @@ }, of, prelude::*, + sync::aref::{ + AlwaysRefCounted, + RefCounted, // + }, types::Opaque, ThisModule, // };
@@ -534,7 +538,7 @@ pub fn optional_irq_by_name(&self, name: &CStr) -> Result<IrqRequest<'_>> {impl <'a>crate ::dma::Device <'a>for Device <device::Core <'a>> {}// SAFETY: Instances of `Device` are always reference-counted. -unsafe impl crate ::sync::aref::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_ref ().as_raw ()) };
@@ -546,6 +550,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount +// is non-zero and it is okay to obtain an `ARef<Device>` from it. +unsafe impl AlwaysRefCounted for Device {} +impl <Ctx : device::DeviceContext >AsRef <device::Device <Ctx >>for Device <Ctx > {fn as_ref (&self) -> &device::Device <Ctx > {// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
rust/kernel/pwm.rs +10 -2
@@ -13,7 +13,11 @@ devres, error::{self, to_result}, prelude::*, - sync::aref::{ARef, AlwaysRefCounted}, + sync::aref::{ + ARef, + AlwaysRefCounted, + RefCounted, // + }, types::Opaque, // };use core::{
@@ -627,7 +631,7 @@ pub fn new<'a>( }// SAFETY: Implements refcounting for `Chip` using the embedded `struct device`. -unsafe impl <T :PwmOps >AlwaysRefCounted for Chip <T > { +unsafe impl <T :PwmOps >RefCounted for Chip <T > {#[inline] fn inc_ref (&self) {// SAFETY: `self.0.get()` points to a valid `pwm_chip` because `self` exists.
@@ -645,6 +649,10 @@ unsafe fn dec_ref(obj: NonNull<Chip<T>>) { } } +// SAFETY: All instances of `Chip<T>` are reference counted, so a `&Chip<T>` proves that the +// refcount is non-zero and it is okay to obtain an `ARef<Chip<T>>` from it. +unsafe impl <T :PwmOps >AlwaysRefCounted for Chip <T > {} +// SAFETY: `Chip` is a wrapper around `*mut bindings::pwm_chip`. The underlying C // structure's state is managed and synchronized by the kernel's device model // and PWM core locking mechanisms. Therefore, it is safe to move the `Chip`
rust/kernel/serdev.rs +9 -2
@@ -17,7 +17,10 @@ of, prelude::*, sync::{ - aref::AlwaysRefCounted, + aref::{ +AlwaysRefCounted , +RefCounted ,// + }, Mutex, // }, time::Jiffies,
@@ -570,7 +573,7 @@ unsafe impl<Ctx: device::DeviceContext> device::AsBusDevice<Ctx> for Device<Ctx> kernel::impl_device_context_into_aref!(Device );// SAFETY: Instances of `Device` are always reference-counted. -unsafe impl AlwaysRefCounted for Device { +unsafe impl RefCounted for Device {fn inc_ref (&self) { self.as_ref ().inc_ref (); }
@@ -581,6 +584,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount +// is non-zero and it is okay to obtain an `ARef<Device>` from it. +unsafe impl AlwaysRefCounted for Device {} +impl <Ctx : device::DeviceContext >AsRef <device::Device <Ctx >>for Device <Ctx > {fn as_ref (&self) -> &device::Device <Ctx > {// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
rust/kernel/sync/aref.rs +39 -24
162 lines not on this page · raw message
rust/kernel/task.rs +11 -2
@@ -10,7 +10,12 @@ pid_namespace::PidNamespace, prelude::*, sync::aref::ARef, - types::{NotThreadSafe, Opaque}, + types::{ +AlwaysRefCounted , +NotThreadSafe , +Opaque , +RefCounted ,// + }, };use core::{ ops::Deref ,
@@ -347,7 +352,7 @@ pub fn group_leader(&self) -> &Task { }// SAFETY: The type invariants guarantee that `Task` is always refcounted. -unsafe impl crate ::sync::aref::AlwaysRefCounted for Task { +unsafe impl RefCounted for Task {#[inline] fn inc_ref (&self) {// SAFETY: The existence of a shared reference means that the refcount is nonzero.
@@ -361,6 +366,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<Self>) { } } +// SAFETY: All instances of `Task` are reference counted, so a `&Task` proves that the refcount is +// non-zero and it is okay to obtain an `ARef<Task>` from it. +unsafe impl AlwaysRefCounted for Task {} +impl PartialEq for Task {#[inline] fn eq (&self, other: &Self ) ->bool {
rust/kernel/types.rs +9 -3
@@ -18,9 +18,15 @@ ForLt, // }; -pub use crate ::owned::{ -Ownable , -Owned ,// +pub use crate ::{ + owned::{ +Ownable , +Owned ,// + }, + sync::aref::{ +AlwaysRefCounted , +RefCounted ,// + },// };/// Used to transfer ownership to and from foreign (non-Rust) languages.
rust/kernel/usb.rs +14 -3
@@ -18,7 +18,10 @@ to_result, // }, prelude::*, - sync::aref::AlwaysRefCounted, + sync::aref::{ + AlwaysRefCounted, + RefCounted, // + }, types::Opaque, ThisModule, // };
@@ -373,7 +376,7 @@ fn as_ref(&self) -> &Device { }// SAFETY: Instances of `Interface` are always reference-counted. -unsafe impl AlwaysRefCounted for Interface { +unsafe impl RefCounted for Interface {#[inline] fn inc_ref (&self) {// SAFETY: The invariants of `Interface` guarantee that `self.as_raw()`
@@ -389,6 +392,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `Interface` are reference counted, so a `&Interface` proves that the +// refcount is non-zero and it is okay to obtain an `ARef<Interface>` from it. +unsafe impl AlwaysRefCounted for Interface {} +// SAFETY: A `Interface` is always reference-counted and can be released from any thread. unsafe impl Send for Interface {}
@@ -426,7 +433,7 @@ fn as_raw(&self) -> *mut bindings::usb_device { kernel::impl_device_context_into_aref!(Device );// SAFETY: Instances of `Device` are always reference-counted. -unsafe impl AlwaysRefCounted for Device { +unsafe impl RefCounted for Device {#[inline] fn inc_ref (&self) {// SAFETY: The invariants of `Device` guarantee that `self.as_raw()`
@@ -442,6 +449,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) { } } +// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount +// is non-zero and it is okay to obtain an `ARef<Device>` from it. +unsafe impl AlwaysRefCounted for Device {} +impl <Ctx : device::DeviceContext >AsRef <device::Device <Ctx >>for Device <Ctx > {fn as_ref (&self) -> &device::Device <Ctx > {// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
rust/kernel/workqueue.rs +4 -4
@@ -192,7 +192,7 @@ sync::{ aref::{ARef , -AlwaysRefCounted ,// +RefCounted ,// }, Arc, LockClassKey, //
@@ -954,7 +954,7 @@ unsafe impl<T, const ID: u64> RawDelayedWorkItem<ID> for Pin<KBox<T>>// implementation of `WorkItemPointer` for `ARef<T>`. unsafe impl <T ,const ID :u64 >WorkItemPointer <ID >for ARef <T >where -T :AlwaysRefCounted , +T :RefCounted ,T :WorkItem <ID ,Pointer =Self >,T :HasWork <T ,ID >, {
@@ -987,7 +987,7 @@ unsafe impl<T, const ID: u64> WorkItemPointer<ID> for ARef<T>// requirements of `WorkItemPointer`. unsafe impl <T ,const ID :u64 >RawWorkItem <ID >for ARef <T >where -T :AlwaysRefCounted , +T :RefCounted ,T :WorkItem <ID ,Pointer =Self >,T :HasWork <T ,ID >, {
@@ -1020,7 +1020,7 @@ unsafe impl<T, const ID: u64> RawDelayedWorkItem<ID> for ARef<T> where T: WorkItem<ID, Pointer = Self>, T: HasDelayedWork<T, ID>, - T: AlwaysRefCounted, + T: RefCounted, { }
Signature · 1 line
2.54.0
[email protected]
AI reviewRe: [PATCH v22 4/5] rust: rename `AlwaysRefCounted` to `RefCounted`
Sashiko has reviewed this patch and found no issues.
Quoted 20 lines
From: Oliver Mangold <[email protected]>
There are types where it may both be reference counted in some cases and owned in others. For such types, obtaining an
ARef<T>from a&Tmay be unsound, as it allows creation of anARef<T>from a&Owned<T>.Therefore, we split
AlwaysRefCountedintoRefCounted(whichARef<T>would require) and a marker trait to indicate that the&T->ARef<T>conversion is sound for the type. A type that implementsOwnablemay only implement the marker trait if it allows anARef<T>to exist together with anOwned<T>.- Rename
AlwaysRefCountedtoRefCounted.
- Add a new unsafe traitAlwaysRefCounted.
- Implement the new traitAlwaysRefCountedfor the newly renamedRefCountedimplementations. This leaves functionality of existing implementers ofAlwaysRefCountedintact.Suggested-by Alice Ryhl <[email protected]>Signed-off-by Oliver Mangold <[email protected]>
Quoted 8 lines
[ Andreas: Updated commit message, rebased on v7.4-rc2, converted new
implementers, relaxed theForeignOwnablebound forARef<T>, updated safety comments. ]Acked-by Igor Korotin <[email protected]>Acked-by Danilo Krummrich <[email protected]>Acked-by Viresh Kumar <[email protected]>Co-developed-by Andreas Hindborg <[email protected]>Signed-off-by Andreas Hindborg <[email protected]>
Sashiko has reviewed this patch and found no issues.
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=4
Andreas Hindborg
maintainerPATCH v22 5/5 rust: Add `OwnableIntoShared` and `OwnableTryFromShared`
In reply to Andreas HindborgFrom: Oliver Mangold <[email protected]>
Types implementing these traits can safely convert between an ARef<T> and an Owned<T>.
OwnableIntoShared provides the infallible conversion from Owned<T> to ARef<T>. OwnableTryFromShared provides the fallible conversion from ARef<T> back to Owned<T>, which succeeds only when no Owned<T> exists for the object and the requirements for creating one are satisfied. For a type that does not allow other references to exist together with an Owned<T>, this means that the ARef<T> must be the only reference to the object.
The two conversions are provided by separate traits because they have different conditions for existing. Some types can never become unique again after having been shared, and such types can implement OwnableIntoShared only.
This is useful for types which generally are accessed through an ARef but have methods which can only safely be called when the reference is unique, like e.g. block::mq::Request::end_ok().
[ Andreas: Fix formatting, update documentation, fix error handling in
examples. Split OwnableRefCounted into two traits. ]
--- rust/kernel/owned.rs | 165 ++++++++++++++++++++++++++++++++++++++++++++++- rust/kernel/sync/aref.rs | 16 ++++- rust/kernel/types.rs | 2 + 3 files changed, 181 insertions(+), 2 deletions(-)
rust/kernel/owned.rs +164 -1
@@ -14,6 +14,10 @@ pin::Pin, ptr::NonNull, // }; +use kernel::{ + sync::aref::ARef , + types::RefCounted ,// +};use kernel::types::ForeignOwnable ;
@@ -28,7 +32,9 @@/// /// Note: The underlying object is not required to provide internal reference counting, because it /// represents a unique, owned reference. If reference counting (on the Rust side) is required, -/// [`RefCounted`](crate::types::RefCounted) should be implemented. +/// [`RefCounted`] should be implemented. [`OwnableIntoShared`] should be implemented if conversion +/// from unique to shared (reference counted) ownership is needed, and [`OwnableTryFromShared`] if +/// conversion from shared back to unique ownership is needed. /// /// # Access model ///
@@ -329,3 +335,160 @@ unsafe fn borrow_mut<'a>(ptr: *mut kernel::ffi::c_void) -> Self::BorrowedMut<'a>unsafe {Pin ::new_unchecked (inner) } } } + +/// A trait for types that support converting a unique reference [`Owned<Self>`] into a shared +/// reference [`ARef<Self>`]. +/// +/// The conversion consumes the [`Owned`], so it cannot fail. Implementing this trait does not make +/// the opposite conversion available. Types that can become unique again after having been shared +/// can implement [`OwnableTryFromShared`] in addition. +/// +/// # Examples +/// +/// A minimal example implementation of [`OwnableIntoShared`], [`OwnableTryFromShared`], +/// [`Ownable`] and its usage with [`ARef`] and [`Owned`] looks like this: +/// +/// ``` +/// # #![expect(clippy::disallowed_names)] +/// # use core::ptr::NonNull; +/// # use kernel::alloc::{flags, kbox::KBox, AllocError}; +/// # use kernel::sync::aref::{ARef, RefCounted}; +/// # use kernel::sync::atomic::Acquire; +/// # use kernel::sync::Refcount; +/// # use kernel::types::{Owned, Ownable, OwnableIntoShared, OwnableTryFromShared}; +/// // An internally refcounted struct for demonstration purposes. +/// // +/// // # Invariants +/// // +/// // - `refcount` counts the live references to the object, so the object is valid while +/// // `refcount` is non-zero. +/// // - `Foo` does not allow other references to exist together with an `Owned<Foo>`: while an +/// // `Owned<Foo>` exists, `refcount` is 1 and no `ARef<Foo>` exists. +/// struct Foo { +/// refcount: Refcount, +/// } +/// +/// impl Foo { +/// fn new() -> Result<Owned<Self>> { +/// // We are just using a `KBox` here to handle the actual allocation, as our `Foo` is +/// // not actually a C-allocated object. +/// // INVARIANT: We initialize `refcount` to 1, counting the reference held by the +/// // returned `Owned<Foo>`. No `ARef<Foo>` exists for the new object. +/// let result = KBox::new( +/// Foo { +/// refcount: Refcount::new(1), +/// }, +/// flags::GFP_KERNEL, +/// )?; +/// let result = KBox::into_non_null(result); +/// // SAFETY: +/// // - We just allocated the `Self`, thus it is valid until the refcount drops to zero. +/// // - No other pointer to the allocation exists, so this is the only `Owned<Foo>` and +/// // no other reference to the `Foo` exists. Thus access through the `Owned<Foo>` is +/// // sound, and it can be used from any thread that `Foo` can be used from. +/// // - The `Foo` is not moved until it is freed in `dec_ref`. +/// Ok(unsafe { Owned::from_raw(result) }) +/// } +/// } +/// +/// // SAFETY: We increment and decrement the refcount 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.inc(); +/// } +/// +/// unsafe fn dec_ref(this: NonNull<Self>) { +/// // SAFETY: By requirement on calling this function, the refcount is non-zero, +/// // implying the underlying object is valid. +/// let refcount = unsafe { &this.as_ref().refcount }; +/// if refcount.dec_and_test() { +/// // SAFETY: The refcount reached zero, so by requirement on calling this function +/// // no reference to the object remains and it will no longer be used. We can +/// // reclaim the allocation by passing ownership back to the [`KBox`], which frees +/// // the `Foo` when dropped. +/// drop(unsafe { KBox::from_raw(this.as_ptr()) }); +/// } +/// } +/// } +/// +/// impl OwnableIntoShared for Foo { +/// fn into_shared(this: Owned<Self>) -> ARef<Self> { +/// // SAFETY: By the type invariants of `Foo`, an `Owned<Foo>` holds the only reference +/// // (refcount 1). We consume the `Owned<Foo>` and transfer the reference to the new +/// // `ARef`. +/// unsafe { ARef::from_raw(Owned::into_raw(this)) } +/// } +/// } +/// +/// impl OwnableTryFromShared for Foo { +/// fn try_from_shared(this: ARef<Self>) -> Result<Owned<Self>, ARef<Self>> { +/// // `this` is a live reference, so the refcount cannot drop below 1, and it can only +/// // grow through an existing reference. Thus observing 1 means that `this` is the only +/// // reference to the object. The `Acquire` ordering synchronizes with the release +/// // decrements of references dropped on other threads. +/// if this.refcount.as_atomic().load(Acquire) == 1 { +/// // SAFETY: The `Foo` is valid and `this` holds the only reference to it, so we +/// // can transfer this last reference to the returned `Owned<Foo>`. No other +/// // reference to the `Foo` exists, so this is the only `Owned<Foo>` and access +/// // through it is sound. The `Foo` is not moved until it is freed in `dec_ref`. +/// // INVARIANT: `refcount` is 1 and we consumed the only `ARef<Foo>`. +/// Ok(unsafe { Owned::from_raw(ARef::into_raw(this)) }) +/// } else { +/// Err(this) +/// } +/// } +/// } +/// +/// 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()?; +/// let foo = ARef::from(foo); +/// { +/// let bar = foo.clone(); +/// assert!(Owned::try_from(bar).is_err()); +/// } +/// assert!(Owned::try_from(foo).is_ok()); +/// # Ok::<(), Error>(()) +/// ``` +pub trait OwnableIntoShared :RefCounted +Ownable +Sized { +/// Converts the [`Owned`] into an [`ARef`]. +fn into_shared (this:Owned <Self >) ->ARef <Self >; +} + +/// A trait for types that support converting a shared reference [`ARef<Self>`] back into a unique +/// reference [`Owned<Self>`]. +/// +/// The conversion can only succeed when no [`Owned`] exists for the object, and when the +/// requirements for creating one are satisfied, so it is fallible. For a type that does not allow +/// other references to exist together with an [`Owned`], this means that the [`ARef`] must be the +/// only reference to the object. See the *Access model* section of [`Ownable`]. +/// +/// Not all types that implement [`OwnableIntoShared`] are able to become unique again after having +/// been shared, so this capability is provided by a separate trait. +/// +/// # Examples +/// +/// See the example for [`OwnableIntoShared`]. +pub trait OwnableTryFromShared :RefCounted +Ownable +Sized { +/// Checks if the [`ARef`] can be converted to an [`Owned`] and converts it if that is the case. +/// Otherwise it returns again an [`ARef`] to the same underlying object. +fn try_from_shared (this:ARef <Self >) ->Result <Owned <Self >,ARef <Self >>; +} + +impl <T :OwnableTryFromShared >TryFrom <ARef <T >>for Owned <T > { +type Error =ARef <T >; +/// Tries to convert the [`ARef`] to an [`Owned`] by calling +/// [`try_from_shared()`](OwnableTryFromShared::try_from_shared). In case the conversion is not +/// possible, it returns again an [`ARef`] to the same underlying object. +#[inline] +fn try_from (b:ARef <T >) ->Result <Owned <T >,Self ::Error > { +T ::try_from_shared (b) + } +}
rust/kernel/sync/aref.rs +15 -1
@@ -23,6 +23,10 @@ ops::Deref, ptr::NonNull, // }; +use kernel::types::{ +OwnableIntoShared , +Owned ,// +};use crate ::{ prelude::*,
@@ -40,7 +44,10 @@/// Note: Implementing this trait allows types to be wrapped in an [`ARef<Self>`]. It requires an /// internal reference count and provides only shared references. If unique references are required /// [`Ownable`](crate::types::Ownable) should be implemented which allows types to be wrapped in an -/// [`Owned<Self>`](crate::types::Owned). +/// [`Owned<Self>`](crate::types::Owned). Implementing the trait [`OwnableIntoShared`] allows to +/// convert a unique reference into a shared one (i.e. [`Owned<Self>`](crate::types::Owned) into +/// [`ARef<Self>`]), and implementing +/// [`OwnableTryFromShared`](crate::types::OwnableTryFromShared) allows to convert back. /// /// # Safety ///
@@ -193,6 +200,13 @@ fn from(b: &T) -> Self { } } +impl <T :OwnableIntoShared >From <Owned <T >>for ARef <T > { +#[inline] +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 we're about to
rust/kernel/types.rs +2 -0
@@ -21,6 +21,8 @@pub use crate ::{ owned::{Ownable , +OwnableIntoShared , +OwnableTryFromShared ,Owned ,// }, sync::aref::{
Signature · 1 line
2.54.0
[email protected]
AI reviewRe: [PATCH v22 5/5] rust: Add `OwnableIntoShared` and `OwnableTryFromShared`
Thank you for your contribution! Sashiko AI review found 1 potential issue to consider: - [Low] rust: separate use blocks instead of single vertical import block --
Thank you for your contribution! Sashiko AI review found 1 potential issue to consider:
- [Low] rust: separate use blocks instead of single vertical import block
--
commit eb9ded53e4184ea08932194e99ba6dc1bce8d3eb
Author: Oliver Mangold <[email protected]>
rust: Add OwnableIntoShared and OwnableTryFromShared
This commit introduces the OwnableIntoShared and OwnableTryFromShared traits to support converting between Owned<T> and ARef<T>.
Quoted 14 lines
rust/kernel/owned.rs +4
-0@@ -14,6 +14,10 @@ pin::Pin, ptr::NonNull, // }; +use kernel::{ + sync::aref::ARef , + types::RefCounted ,// +};use kernel::types::ForeignOwnable ;
[ ... ]
Quoted 5 lines
rust/kernel/sync/aref.rs +0
-0
rust/kernel/sync/aref.rs line 32
Quoted 10 lines
rust/kernel/sync/aref.rs +4
-0@@ -23,6 +23,10 @@ ops::Deref, ptr::NonNull, // }; +use kernel::types::{ +OwnableIntoShared , +Owned ,// +};use crate ::{ prelude::*,
[Severity: Low]
This isn't a bug, but both files add a separate use block instead of merging the new imports into the existing kernel/crate vertical import blocks (grouping ForeignOwnable with RefCounted in owned.rs, and OwnableIntoShared and Owned under crate::types in aref.rs).
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=5