Re: [PATCH v2 1/2] rust: move ARef and AlwaysRefCounted to sync::aref

["Benno Lossin" <lossin@kernel.org>]

On Wed Jun 25, 2025 at 1:11 PM CEST, Shankari Anand wrote:
> diff --git a/rust/kernel/sync/aref.rs b/rust/kernel/sync/aref.rs
> new file mode 100644
> index 000000000000..93a23b493e21
> --- /dev/null
> +++ b/rust/kernel/sync/aref.rs
> @@ -0,0 +1,170 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Atomic reference-counted pointer abstraction.

I'd say this module is about supporting objects with builtin reference
counting.

> +//!
> +//! This module provides [`ARef<T>`], an owned reference to a value that implements
> +//! [`AlwaysRefCounted`] — an unsafe trait for types that manage their own reference count.

I would lead with comparing `ARef<T>` to `Arc<T>` and only later mention
`AlwaysRefCounted`.

> +//!
> +//! It is based on the Linux kernel's manual reference counting model and is typically used
> +//! with C types that implement reference counting (e.g., via `refcount_t` or `kref`).
> +//!
> +//! For Rust-managed objects, prefer using [`Arc`](crate::sync::Arc) instead.
> +
> +use core::{
> +    marker::PhantomData,
> +    mem::ManuallyDrop,
> +    ops::Deref,
> +    ptr::NonNull,
> +};
> +
> +/// Trait for types that are _always_ reference-counted.
> +///
> +/// This trait allows types to define custom reference increment and decrement logic.
> +/// It enables safe conversion from a shared reference `&T` to an owned [`ARef<T>`].
> +///
> +/// This is usually implemented by wrappers around C types with manual refcounting.
> +///
> +/// For purely Rust-managed memory, consider using [`Arc`](crate::sync::Arc) instead.
> +///
> +/// # Safety
> +///
> +/// Implementers must ensure that:
> +///
> +/// - Calling [`AlwaysRefCounted::inc_ref`] keeps the object alive in memory until a matching [`AlwaysRefCounted::dec_ref`] is called.
> +/// - The object is always managed by a reference count; it must never be stack-allocated or
> +///   otherwise untracked.
> +/// - When the count reaches zero in [`AlwaysRefCounted::dec_ref`], the object is properly freed and no further
> +///   access occurs.
> +///
> +/// Failure to follow these rules may lead to use-after-free or memory corruption.

You also rephrased these docs, can you do that in a separate patch?

> +

Newline?

---
Cheers,
Benno

> +pub unsafe trait AlwaysRefCounted {
> +    /// Increments the reference count on the object.
> +    fn inc_ref(&self);
> +
> +    /// Decrements the reference count on the object.
> +    ///
> +    /// Frees the object when the count reaches zero.
> +    ///
> +    /// # Safety
> +    ///
> +    /// Callers must ensure that there was a previous matching increment to the reference count,
> +    /// and that the object is no longer used after its reference count is decremented (as it may
> +    /// result in the object being freed), unless the caller owns another increment on the refcount
> +    /// (e.g., it calls [`AlwaysRefCounted::inc_ref`] twice, then calls
> +    /// [`AlwaysRefCounted::dec_ref`] once).
> +    unsafe fn dec_ref(obj: NonNull<Self>);
> +}