[08/13] rust: introduce `ARef`
Commit Message
From: Wedson Almeida Filho <walmeida@microsoft.com>
This is an owned reference to an object that is always ref-counted. This
is meant to be used in wrappers for C types that have their own ref
counting functions, for example, tasks, files, inodes, dentries, etc.
Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com>
---
rust/kernel/types.rs | 107 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 107 insertions(+)
Comments
On Thu, 30 Mar 2023 01:39:49 -0300
Wedson Almeida Filho <wedsonaf@gmail.com> wrote:
> From: Wedson Almeida Filho <walmeida@microsoft.com>
>
> This is an owned reference to an object that is always ref-counted. This
> is meant to be used in wrappers for C types that have their own ref
> counting functions, for example, tasks, files, inodes, dentries, etc.
>
> Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com>
Reviewed-by: Gary Guo <gary@garyguo.net>
> ---
> rust/kernel/types.rs | 107 +++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 107 insertions(+)
>
> diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
> index dbfae9bb97ce..b071730253c7 100644
> --- a/rust/kernel/types.rs
> +++ b/rust/kernel/types.rs
> @@ -6,8 +6,10 @@ use crate::init::{self, PinInit};
> use alloc::boxed::Box;
> use core::{
> cell::UnsafeCell,
> + marker::PhantomData,
> mem::MaybeUninit,
> ops::{Deref, DerefMut},
> + ptr::NonNull,
> };
>
> /// Used to transfer ownership to and from foreign (non-Rust) languages.
> @@ -295,6 +297,111 @@ opaque_init_funcs! {
> "Rust" manual_init4(arg1: A1, arg2: A2, arg3: A3, arg4: A4);
> }
>
> +/// 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.
> +///
> +/// # 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 {
> + /// 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>);
> +}
> +
> +/// An owned reference to an always-reference-counted object.
> +///
> +/// The object's reference count is automatically decremented when an instance of [`ARef`] is
> +/// dropped. It is also automatically incremented when a new instance is created via
> +/// [`ARef::clone`].
> +///
> +/// # Invariants
> +///
> +/// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`ARef`] instance. In
> +/// particular, the [`ARef`] instance owns an increment on the underlying object's reference count.
> +pub struct ARef<T: AlwaysRefCounted> {
> + ptr: NonNull<T>,
> + _p: PhantomData<T>,
> +}
> +
> +impl<T: AlwaysRefCounted> ARef<T> {
> + /// Creates a new instance of [`ARef`].
> + ///
> + /// It takes over an increment of the reference count on the underlying object.
> + ///
> + /// # Safety
> + ///
> + /// Callers must ensure that the reference count was incremented at least once, and that they
> + /// are properly relinquishing one increment. That is, if there is only one increment, callers
> + /// must not use the underlying object anymore -- it is only safe to do so via the newly
> + /// created [`ARef`].
> + pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
> + // INVARIANT: The safety requirements guarantee that the new instance now owns the
> + // increment on the refcount.
> + Self {
> + ptr,
> + _p: PhantomData,
> + }
> + }
> +}
> +
> +impl<T: AlwaysRefCounted> Clone for ARef<T> {
> + fn clone(&self) -> Self {
> + self.inc_ref();
> + // SAFETY: We just incremented the refcount above.
> + unsafe { Self::from_raw(self.ptr) }
> + }
> +}
> +
> +impl<T: AlwaysRefCounted> Deref for ARef<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: AlwaysRefCounted> From<&T> for ARef<T> {
> + fn from(b: &T) -> Self {
> + b.inc_ref();
> + // SAFETY: We just incremented the refcount above.
> + unsafe { Self::from_raw(NonNull::from(b)) }
> + }
> +}
> +
> +impl<T: AlwaysRefCounted> Drop for ARef<T> {
> + fn drop(&mut self) {
> + // SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to
> + // decrement.
> + unsafe { T::dec_ref(self.ptr) };
> + }
> +}
> +
> /// A sum type that always holds either a value of type `L` or `R`.
> pub enum Either<L, R> {
> /// Constructs an instance of [`Either`] containing a value of type `L`.
@@ -6,8 +6,10 @@ use crate::init::{self, PinInit};
use alloc::boxed::Box;
use core::{
cell::UnsafeCell,
+ marker::PhantomData,
mem::MaybeUninit,
ops::{Deref, DerefMut},
+ ptr::NonNull,
};
/// Used to transfer ownership to and from foreign (non-Rust) languages.
@@ -295,6 +297,111 @@ opaque_init_funcs! {
"Rust" manual_init4(arg1: A1, arg2: A2, arg3: A3, arg4: A4);
}
+/// 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.
+///
+/// # 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 {
+ /// 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>);
+}
+
+/// An owned reference to an always-reference-counted object.
+///
+/// The object's reference count is automatically decremented when an instance of [`ARef`] is
+/// dropped. It is also automatically incremented when a new instance is created via
+/// [`ARef::clone`].
+///
+/// # Invariants
+///
+/// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`ARef`] instance. In
+/// particular, the [`ARef`] instance owns an increment on the underlying object's reference count.
+pub struct ARef<T: AlwaysRefCounted> {
+ ptr: NonNull<T>,
+ _p: PhantomData<T>,
+}
+
+impl<T: AlwaysRefCounted> ARef<T> {
+ /// Creates a new instance of [`ARef`].
+ ///
+ /// It takes over an increment of the reference count on the underlying object.
+ ///
+ /// # Safety
+ ///
+ /// Callers must ensure that the reference count was incremented at least once, and that they
+ /// are properly relinquishing one increment. That is, if there is only one increment, callers
+ /// must not use the underlying object anymore -- it is only safe to do so via the newly
+ /// created [`ARef`].
+ pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
+ // INVARIANT: The safety requirements guarantee that the new instance now owns the
+ // increment on the refcount.
+ Self {
+ ptr,
+ _p: PhantomData,
+ }
+ }
+}
+
+impl<T: AlwaysRefCounted> Clone for ARef<T> {
+ fn clone(&self) -> Self {
+ self.inc_ref();
+ // SAFETY: We just incremented the refcount above.
+ unsafe { Self::from_raw(self.ptr) }
+ }
+}
+
+impl<T: AlwaysRefCounted> Deref for ARef<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: AlwaysRefCounted> From<&T> for ARef<T> {
+ fn from(b: &T) -> Self {
+ b.inc_ref();
+ // SAFETY: We just incremented the refcount above.
+ unsafe { Self::from_raw(NonNull::from(b)) }
+ }
+}
+
+impl<T: AlwaysRefCounted> Drop for ARef<T> {
+ fn drop(&mut self) {
+ // SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to
+ // decrement.
+ unsafe { T::dec_ref(self.ptr) };
+ }
+}
+
/// A sum type that always holds either a value of type `L` or `R`.
pub enum Either<L, R> {
/// Constructs an instance of [`Either`] containing a value of type `L`.