rust: move ARef and AlwaysRefCounted to sync::aref
PATCH v4 1/1 rust: move ARef and AlwaysRefCounted to sync::aref
Move the definitions of ARef and AlwaysRefCounted from types.rs to a new file sync/aref.rs.
Define the corresponding aref module under rust/kernel/sync.rs. These types are better grouped in sync.
To avoid breaking existing imports, they are re-exported from types.rs. Drop unused imports mem::ManuallyDrop, ptr::NonNull from types.rs, they are now only used in sync/aref.rs, where they are already imported.
---
v3 -> v4: Changed the position of the use statement, removed the either type that was pasted in aref.rs by mistake.
I'll separate the patches for updation of call-sites subsystem-wise and send them subsequently.
--- rust/kernel/sync.rs | 1 + rust/kernel/sync/aref.rs | 154 +++++++++++++++++++++++++++++++++++++++ rust/kernel/types.rs | 154 +-------------------------------------- 3 files changed, 158 insertions(+), 151 deletions(-) create mode 100644 rust/kernel/sync/aref.rs
rust/kernel/sync.rs +1 -0
@@ -10,6 +10,7 @@use pin_init;mod arc; +pub mod aref;pub mod completion;mod condvar;pub mod lock;
rust/kernel/sync/aref.rs new file +154 -0
154 lines not on this page · raw message
rust/kernel/types.rs +3 -151
170 lines not on this page · raw message
base-commit: 2009a2d5696944d85c34d75e691a6f3884e787c0
Signature · 1 line
2.34.1
Quoted 5 lines · Shankari Anand
Move the definitions of
ARefandAlwaysRefCountedfromtypes.rsto a new filesync/aref.rs.
Define the correspondingarefmodule underrust/kernel/sync.rs. These types are better grouped insync.
Quoted 7 lines
To avoid breaking existing imports, they are re-exported from
types.rs. Drop unused importsmem::ManuallyDrop,ptr::NonNullfromtypes.rs, they are now only used insync/aref.rs, where they are already imported.Suggested-by Benno Lossin <[email protected]>Signed-off-by Shankari Anand <[email protected]>
One comment below, but that can be fixed when applying the patch.
Quoted 12 lines
rust/kernel/sync/aref.rs new file +6
-0@@ -0,0 +1,154 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Built-in Reference Counting Support + +use core::{marker::PhantomData , mem::ManuallyDrop , ops::Deref , ptr::NonNull }; +
rust/kernel/sync/aref.rs line 16
Quoted 10 lines
rust/kernel/sync/aref.rs new file +10
-0+/// Types that are _always_ reference counted. +/// +/// It allows such types to define their own custom ref increment and decrement functions. +/// Additionally, it allows users to convert from a shared reference `&T` to an owned reference +/// [`ARef<T>`]. +/// +/// This is usually implemented by wrappers to existing structures on the C side of the code. For +/// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted +/// instances of a type. +
There is a missing /// in this line, but Miguel can fix that when picking the patch.
---
Cheers,
Benno
Quoted 9 lines
rust/kernel/sync/aref.rs new file +9
-0+/// # Safety +/// +/// Implementers must ensure that increments to the reference count keep the object alive in memory +/// at least until matching decrements are performed. +/// +/// Implementers must also ensure that all instances are reference-counted. (Otherwise they +/// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object +/// alive.) +pub unsafe trait AlwaysRefCounted {
Quoted 2 lines · Shankari Anand
+//! Built-in Reference Counting Support
What is it meant by "built-in" here? Could we just use "Reference counting support."? Or do you have another suggestion, Benno?
(No need for a new version, I can modify it on apply)
Thanks!
Cheers,
Miguel
Benno Lossin
reviewerQuoted 7 lines · Miguel Ojeda
Quoted 2 lines · Shankari Anand
+//! Built-in Reference Counting Support
What is it meant by "built-in" here? Could we just use "Reference counting support."? Or do you have another suggestion, Benno?
ARef specifically is about supporting types that already have their own "built-in" reference counting. I'm not sure if built-in is the best word to describe that, some alternatives are inherent or internal.
Maybe we can just expand the module level docs with:
//! Internal Reference Counting Support.
//!
//! Many C types already have their own reference counting mechanism (e.g. by storing a
//! `refcount_t`). This module provides support for directly using their internal reference count
//! from Rust; instead of making users have to use an additional Rust-reference count in the form of
//! [`Arc`].
//!
//! The smart pointer [`ARef<T>`] acts similarly to [`Arc<T>`] in that it holds a refcount on the
//! underlying object, but this refcount is internal to the object. It essentially is a Rust
//! implementation of the `get_` and `put_` pattern used in C for reference counting.
//!
//! To make use of [`ARef<MyType>`], `MyType` needs to implement [`AlwaysRefCounted`]. It is a trait
//! for accessing the internal reference count of an object of the `MyType` type.Thoughts?
---
Cheers,
Benno
Quoted 4 lines · Benno Lossin
ARefspecifically is about supporting types that already have their own "built-in" reference counting. I'm not sure if built-in is the best word to describe that, some alternatives are inherent or internal.
Yeah, it is a bit ambiguous (e.g. it could also be understood as that the code is always built as built-in, which is true currently).
Quoted 3 lines
Maybe we can just expand the module level docs with:
//! Internal Reference Counting Support.
That would be nice, yeah, please send a patch. I will use "Internal" for the time being so that it matches what you have here. (Inherent sounded also good to me.)
Thanks!
Cheers,
Miguel
Miguel Ojeda
AppliedQuoted 6 lines · Shankari Anand
Move the definitions of
ARefandAlwaysRefCountedfromtypes.rsto a new filesync/aref.rs.
Define the correspondingarefmodule underrust/kernel/sync.rs. These types are better grouped insync.
Quoted 7 lines
To avoid breaking existing imports, they are re-exported from
types.rs. Drop unused importsmem::ManuallyDrop,ptr::NonNullfromtypes.rs, they are now only used insync/aref.rs, where they are already imported.Suggested-by Benno Lossin <[email protected]>Signed-off-by Shankari Anand <[email protected]>
Applied to rust-next -- thanks everyone!
[ Added missing ///. Changed module title. Reworded slightly. - Miguel ]
Cheers,
Miguel