rust: introduce `ARef` (f1fbd6a8) · Commits · EulixOS / Software / Kernel

rust/kernel/types.rs

+107 −0

Original line number	Diff line number	Diff line
		@@ -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.
		@@ -268,6 +270,111 @@ impl<T> Opaque<T> {
		}
		}

		/// 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`.