Skip to contentSkip to conversation

rust: move ARef and AlwaysRefCounted to sync::aref

PATCH Applied Shankari Anand 3 participants 6 messages Jul 15, 2025 – Jul 22, 2025

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

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
index 63c99e015ad6..8fd126788e02 100644
@@ -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
reviewer Reviewed-by on v4 1/1
#1 lore raw
Quoted 5 lines · Shankari Anand

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.

Quoted 7 lines

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.

One comment below, but that can be fixed when applying the patch.

Quoted 12 lines
rust/kernel/sync/aref.rs new file +6 -0
new file mode 100644
index 000000000000..752eef31d45e
@@ -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 {
#2 lore raw
In reply to Shankari Anand
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

reviewer
#3 lore raw
Quoted 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

#4 lore raw
Quoted 4 lines · Benno Lossin

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.

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

Applied
#5 lore raw
In reply to Shankari Anand
Quoted 6 lines · Shankari Anand

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.

Quoted 7 lines

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.

Applied to rust-next -- thanks everyone!

[ Added missing ///. Changed module title. Reworded slightly. - Miguel ]

Cheers,
Miguel