From: Andreas Hindborg <a.hindborg@kernel.org>
To: "Tamir Duberstein" <tamird@kernel.org>,
"Miguel Ojeda" <ojeda@kernel.org>,
"Boqun Feng" <boqun@kernel.org>, "Gary Guo" <gary@garyguo.net>,
"Björn Roy Baron" <bjorn3_gh@protonmail.com>,
"Benno Lossin" <lossin@kernel.org>,
"Alice Ryhl" <aliceryhl@google.com>,
"Trevor Gross" <tmgross@umich.edu>,
"Danilo Krummrich" <dakr@kernel.org>,
"Daniel Almeida" <daniel.almeida@collabora.com>,
"Alexandre Courbot" <acourbot@nvidia.com>,
"Onur Özkan" <work@onurozkan.dev>,
"Matthew Wilcox" <willy@infradead.org>,
"Andrew Morton" <akpm@linux-foundation.org>,
"Lorenzo Stoakes" <ljs@kernel.org>,
"Liam R. Howlett" <liam@infradead.org>,
"Vlastimil Babka" <vbabka@kernel.org>,
"Harry Yoo" <harry@kernel.org>, "Hao Li" <hao.li@linux.dev>,
"Christoph Lameter" <cl@gentwo.org>,
"David Rientjes" <rientjes@google.com>,
"Roman Gushchin" <roman.gushchin@linux.dev>
Cc: Andreas Hindborg <a.hindborg@kernel.org>,
rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org,
linux-fsdevel@vger.kernel.org, linux-mm@kvack.org,
Vlastimil Babka <vbabka@kernel.org>,
"Liam R. Howlett" <liam@infradead.org>,
Lorenzo Stoakes <ljs@kernel.org>
Subject: [PATCH v6 09/12] rust: mm: sheaf: allow use of C initialized static caches
Date: Fri, 20 Nov 2026 14:10:20 +0100 [thread overview]
Message-ID: <20261120-xarray-entry-send-v6-9-1f69d7385f70@kernel.org> (raw)
In-Reply-To: <20261120-xarray-entry-send-v6-0-1f69d7385f70@kernel.org>
Extend the sheaf abstraction to support caches that are never destroyed,
such as caches created by C code at kernel boot time, in addition to
reference-counted caches created through the abstraction.
Introduce `KMemCache<T>` as a transparent wrapper around `kmem_cache` for
static caches with `'static` lifetime. Rename the previous `KMemCache<T>`
to `KMemCacheHandle<T>` to represent caches that are created through the
abstraction, reference-counted, and destroyed when the last reference is
dropped.
Add `Static` and `Dynamic` marker types along with `StaticSheaf` and
`DynamicSheaf` type aliases to distinguish sheaves from each cache type.
The `Sheaf` type now carries lifetime and allocation mode type parameters.
Add `SBox::into_ptr()` and `SBox::static_from_ptr()` methods for passing
allocations through C code via raw pointers.
Add `KMemCache::from_raw()` for wrapping C-initialized static caches and
`Sheaf::refill()` for replenishing a sheaf to a minimum size.
Export `kmem_cache_prefill_sheaf`, `kmem_cache_return_sheaf`,
`kmem_cache_refill_sheaf`, and `kmem_cache_alloc_from_sheaf_noprof` to
allow Rust module code to use the sheaf API.
Cc: Vlastimil Babka <vbabka@suse.cz>
Cc: "Liam R. Howlett" <Liam.Howlett@oracle.com>
Cc: "Matthew Wilcox (Oracle)" <willy@infradead.org>
Cc: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Cc: linux-mm@kvack.org
Acked-by: Vlastimil Babka (SUSE) <vbabka@kernel.org>
Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
mm/slub.c | 4 +
rust/kernel/mm/sheaf.rs | 397 +++++++++++++++++++++++++++++++++++++++++-------
2 files changed, 342 insertions(+), 59 deletions(-)
diff --git a/mm/slub.c b/mm/slub.c
index cd671b934719..21811b9ff791 100644
--- a/mm/slub.c
+++ b/mm/slub.c
@@ -5292,6 +5292,7 @@ kmem_cache_prefill_sheaf(struct kmem_cache *s, gfp_t gfp, unsigned int size)
return sheaf;
}
+EXPORT_SYMBOL(kmem_cache_prefill_sheaf);
/*
* Use this to return a sheaf obtained by kmem_cache_prefill_sheaf()
@@ -5347,6 +5348,7 @@ void kmem_cache_return_sheaf(struct kmem_cache *s, gfp_t gfp,
barn_put_full_sheaf(barn, sheaf);
stat(s, BARN_PUT);
}
+EXPORT_SYMBOL(kmem_cache_return_sheaf);
/*
* Refill a sheaf previously returned by kmem_cache_prefill_sheaf to at least
@@ -5402,6 +5404,7 @@ int kmem_cache_refill_sheaf(struct kmem_cache *s, gfp_t gfp,
*sheafp = sheaf;
return 0;
}
+EXPORT_SYMBOL(kmem_cache_refill_sheaf);
/*
* Allocate from a sheaf obtained by kmem_cache_prefill_sheaf()
@@ -5440,6 +5443,7 @@ kmem_cache_alloc_from_sheaf_noprof(struct kmem_cache *s, gfp_t gfp,
return ret;
}
+EXPORT_SYMBOL(kmem_cache_alloc_from_sheaf_noprof);
unsigned int kmem_cache_sheaf_size(struct slab_sheaf *sheaf)
{
diff --git a/rust/kernel/mm/sheaf.rs b/rust/kernel/mm/sheaf.rs
index 1bc0c3dca900..9afbac202418 100644
--- a/rust/kernel/mm/sheaf.rs
+++ b/rust/kernel/mm/sheaf.rs
@@ -20,22 +20,32 @@
//! - Multiple allocations need to be performed as a batch operation.
//! - Fast-path allocation performance is critical, as sheaf allocations avoid
//! atomic operations by using local locks with preemption disabled. Note
-//! that the abstraction adds reference counting on top of this, see
-//! [`Sheaf`].
+//! that the abstraction adds reference counting on top of this for dynamic
+//! caches, see [`Sheaf`].
//!
//! # Architecture
//!
-//! The sheaf system consists of three main components:
+//! The sheaf system supports two modes of operation:
+//!
+//! - **Static caches**: [`KMemCache`] represents a cache that is never
+//! destroyed, typically one created by C code at kernel boot time. These
+//! have `'static` lifetime and produce [`StaticSheaf`] instances.
+//! - **Dynamic caches**: [`KMemCacheHandle`] owns a cache created through
+//! this abstraction. These are reference-counted, destroyed when the last
+//! reference is dropped, and produce [`DynamicSheaf`] instances.
+//!
+//! Both modes use the same core types:
//!
-//! - [`KMemCache`]: A slab cache configured with sheaf support.
//! - [`Sheaf`]: A pre-filled container of objects from a specific cache.
//! - [`SBox`]: An owned allocation from a sheaf, similar to a `Box`.
//!
//! # Example
//!
+//! Using a dynamically created cache:
+//!
//! ```
//! use kernel::c_str;
-//! use kernel::mm::sheaf::{KMemCache, KMemCacheInit, Sheaf, SBox};
+//! use kernel::mm::sheaf::{KMemCacheHandle, KMemCacheInit, Sheaf, SBox};
//! use kernel::prelude::*;
//!
//! struct MyObject {
@@ -49,7 +59,7 @@
//! }
//!
//! // Create a cache with a sheaf capacity of at least 16 objects.
-//! let cache = KMemCache::<MyObject>::new(c_str!("my_cache"), 16)?;
+//! let cache = KMemCacheHandle::<MyObject>::new(c_str!("my_cache"), 16)?;
//!
//! // Pre-fill a sheaf with 8 objects.
//! let mut sheaf = cache.as_arc_borrow().sheaf(8, GFP_KERNEL)?;
@@ -82,7 +92,115 @@
use kernel::prelude::*;
-use crate::sync::{Arc, ArcBorrow};
+use crate::{
+ sync::{Arc, ArcBorrow},
+ types::Opaque,
+};
+
+/// A slab cache with sheaf support.
+///
+/// This type is a transparent wrapper around a kernel `kmem_cache`. It can be
+/// used with caches created either by C code or via [`KMemCacheHandle`].
+///
+/// When a reference to this type has `'static` lifetime (i.e., `&'static
+/// KMemCache<T>`), it represents a cache that is never destroyed, typically
+/// one created by C code at boot time. Such references produce
+/// [`StaticSheaf`] instances via [`sheaf`].
+///
+/// [`sheaf`]: KMemCache::sheaf
+///
+/// # Type parameter
+///
+/// - `T`: The type of objects managed by this cache. Must implement
+/// [`KMemCacheInit`] to provide initialization logic for allocations.
+#[repr(transparent)]
+pub struct KMemCache<T: KMemCacheInit<T>> {
+ inner: Opaque<bindings::kmem_cache>,
+ _p: PhantomData<T>,
+}
+
+// SAFETY: The C `kmem_cache` is internally synchronized and has no thread
+// affinity, so a `KMemCache<T>` may be sent to another thread if the objects
+// it manages can.
+unsafe impl<T: KMemCacheInit<T> + Send> Send for KMemCache<T> {}
+
+// SAFETY: All operations available through `&KMemCache<T>` (creating sheaves
+// and allocating objects) are internally synchronized by the C side, so the
+// cache may be used from multiple threads concurrently if the objects it
+// manages can be sent between threads.
+unsafe impl<T: KMemCacheInit<T> + Send> Sync for KMemCache<T> {}
+
+impl<T: KMemCacheInit<T>> KMemCache<T> {
+ /// Creates a pre-filled sheaf from this cache.
+ ///
+ /// Allocates a sheaf and pre-fills it with `size` objects. Once created,
+ /// allocations from the sheaf via [`Sheaf::alloc`] are guaranteed to
+ /// succeed until the sheaf is depleted.
+ ///
+ /// # Arguments
+ ///
+ /// - `size`: The number of objects to pre-allocate. Must not be zero. If
+ /// `size` exceeds the sheaf capacity of the cache, an "oversize" sheaf
+ /// is allocated. Oversize sheaves are slower to create, and they are
+ /// flushed and freed rather than cached for reuse when returned.
+ /// - `gfp`: Allocation flags controlling how memory is obtained. Use
+ /// [`GFP_KERNEL`] for normal allocations that may sleep, or
+ /// [`GFP_NOWAIT`] for non-blocking allocations.
+ ///
+ /// # Errors
+ ///
+ /// Returns [`ENOMEM`] if the sheaf or its objects could not be allocated,
+ /// or if `size` is zero.
+ #[inline]
+ pub fn sheaf(
+ &'static self,
+ size: usize,
+ gfp: kernel::alloc::Flags,
+ ) -> Result<Sheaf<'static, T, Static>> {
+ // SAFETY: `self.as_raw()` returns a valid cache pointer, and `size`
+ // has been validated to fit in a `c_uint`.
+ let ptr = unsafe {
+ bindings::kmem_cache_prefill_sheaf(self.inner.get(), gfp.as_raw(), size.try_into()?)
+ };
+
+ // INVARIANT: `ptr` was returned by `kmem_cache_prefill_sheaf` and is
+ // non-null (checked below). `cache` is the cache from which this sheaf
+ // was created. `dropped` is false since the sheaf has not been returned.
+ Ok(Sheaf {
+ sheaf: NonNull::new(ptr).ok_or(ENOMEM)?,
+ // SAFETY: `self` is a valid reference, so the pointer is non-null.
+ cache: CacheRef::Static(unsafe {
+ NonNull::new_unchecked((&raw const *self).cast_mut())
+ }),
+ dropped: false,
+ _p: PhantomData,
+ })
+ }
+
+ #[inline]
+ fn as_raw(&self) -> *mut bindings::kmem_cache {
+ self.inner.get()
+ }
+
+ /// Creates a reference to a [`KMemCache`] from a raw pointer.
+ ///
+ /// This is useful for wrapping a C-initialized static `kmem_cache`, such as
+ /// the global `radix_tree_node_cachep` used by XArrays.
+ ///
+ /// # Safety
+ ///
+ /// - `ptr` must be a valid pointer to a `kmem_cache` that was created for
+ /// objects of type `T`.
+ /// - The cache must remain valid for the lifetime `'a`.
+ /// - The caller must ensure that the cache was configured appropriately for
+ /// the type `T`, including proper size and alignment.
+ pub unsafe fn from_raw<'a>(ptr: *mut bindings::kmem_cache) -> &'a Self {
+ // SAFETY: The caller guarantees that `ptr` is a valid pointer to a
+ // `kmem_cache` created for objects of type `T`, that it remains valid
+ // for lifetime `'a`, and that the cache is properly configured for `T`.
+ unsafe { &*ptr.cast::<Self>() }
+ }
+}
/// A slab cache with sheaf support.
///
@@ -98,34 +216,38 @@
///
/// # Context
///
-/// Dropping the last reference to a `KMemCache` destroys the cache via
-/// `kmem_cache_destroy`, which may sleep. [`Sheaf`] and [`SBox`] instances
-/// created from the cache each hold a reference, so the last reference may
-/// be dropped when one of those is dropped. The last reference must not be
-/// dropped from a context where sleeping is not allowed.
+/// Dropping the last reference to a `KMemCacheHandle` destroys the cache via
+/// `kmem_cache_destroy`, which may sleep. [`SBox`] instances allocated from
+/// the handle each hold a reference, so the last reference may be dropped
+/// when an [`SBox`] is dropped. The last reference must not be dropped from a
+/// context where sleeping is not allowed.
+///
+/// A [`Sheaf`] created from the handle also holds a reference, but dropping
+/// a [`Sheaf`] never drops the last one. See the `# Lifecycle` section of
+/// [`Sheaf`].
///
/// # Invariants
///
/// - `cache` is a valid pointer to a `kmem_cache` created with
/// `__kmem_cache_create_args`.
/// - The cache is valid for the lifetime of this struct.
-pub struct KMemCache<T: KMemCacheInit<T>> {
- cache: NonNull<bindings::kmem_cache>,
- _p: PhantomData<T>,
+#[repr(transparent)]
+pub struct KMemCacheHandle<T: KMemCacheInit<T>> {
+ cache: NonNull<KMemCache<T>>,
}
-// SAFETY: `KMemCache<T>` owns a `kmem_cache`, which is internally
+// SAFETY: `KMemCacheHandle<T>` owns a `kmem_cache`, which is internally
// synchronized and has no thread affinity. The cache may be destroyed from a
// thread other than the one that created it.
-unsafe impl<T: KMemCacheInit<T> + Send> Send for KMemCache<T> {}
+unsafe impl<T: KMemCacheInit<T> + Send> Send for KMemCacheHandle<T> {}
-// SAFETY: All operations available through `&KMemCache<T>` are
+// SAFETY: All operations available through `&KMemCacheHandle<T>` are
// internally synchronized by the C side, so the cache may be used from
// multiple threads concurrently if the objects it manages can be sent between
// threads.
-unsafe impl<T: KMemCacheInit<T> + Send> Sync for KMemCache<T> {}
+unsafe impl<T: KMemCacheInit<T> + Send> Sync for KMemCacheHandle<T> {}
-impl<T: KMemCacheInit<T>> KMemCache<T> {
+impl<T: KMemCacheInit<T>> KMemCacheHandle<T> {
/// Creates a new slab cache with sheaf support.
///
/// Creates a kernel slab cache for objects of type `T` with at least the
@@ -182,8 +304,7 @@ pub fn new(name: &CStr, sheaf_capacity: u32) -> Result<Arc<Self>>
// `kmem_cache_destroy` is called in `Drop`.
Ok(Arc::new(
Self {
- cache: NonNull::new(ptr).ok_or(ENOMEM)?,
- _p: PhantomData,
+ cache: NonNull::new(ptr.cast()).ok_or(ENOMEM)?,
},
GFP_KERNEL,
)?)
@@ -210,11 +331,11 @@ pub fn new(name: &CStr, sheaf_capacity: u32) -> Result<Arc<Self>>
/// Returns [`ENOMEM`] if the sheaf or its objects could not be allocated,
/// or if `size` is zero.
#[inline]
- pub fn sheaf(
- self: ArcBorrow<'_, Self>,
+ pub fn sheaf<'a>(
+ self: ArcBorrow<'a, Self>,
size: usize,
gfp: kernel::alloc::Flags,
- ) -> Result<Sheaf<T>> {
+ ) -> Result<Sheaf<'a, T, Dynamic>> {
// SAFETY: `self.as_raw()` returns a valid cache pointer, and `size`
// has been validated to fit in a `c_uint`.
let ptr = unsafe {
@@ -226,18 +347,19 @@ pub fn sheaf(
// was created. `dropped` is false since the sheaf has not been returned.
Ok(Sheaf {
sheaf: NonNull::new(ptr).ok_or(ENOMEM)?,
- cache: self.into(),
+ cache: CacheRef::Arc(self.into()),
dropped: false,
+ _p: PhantomData,
})
}
#[inline]
fn as_raw(&self) -> *mut bindings::kmem_cache {
- self.cache.as_ptr()
+ self.cache.as_ptr().cast()
}
}
-impl<T: KMemCacheInit<T>> Drop for KMemCache<T> {
+impl<T: KMemCacheInit<T>> Drop for KMemCacheHandle<T> {
fn drop(&mut self) {
// SAFETY: `self.as_raw()` returns a valid cache pointer that was
// created by `__kmem_cache_create_args`. As all objects allocated from
@@ -250,13 +372,13 @@ fn drop(&mut self) {
/// Trait for types that can be initialized in a slab cache.
///
/// This trait provides the initialization logic for objects allocated from a
-/// [`KMemCache`]. When the slab allocator creates new objects, it invokes the
-/// constructor to ensure objects are in a valid initial state.
+/// [`KMemCache`]. The initializer is called when objects are allocated from a
+/// sheaf via [`Sheaf::alloc`].
///
/// # Implementation
///
-/// Implementors must provide [`init`](KMemCacheInit::init), which returns
-/// a in-place initializer for the type.
+/// Implementors must provide [`init`](KMemCacheInit::init), which returns an
+/// infallible initializer for the type.
///
/// # Example
///
@@ -281,13 +403,34 @@ fn drop(&mut self) {
pub trait KMemCacheInit<T> {
/// Returns an initializer for creating new objects of type `T`.
///
- /// The initializer is applied to newly allocated objects when they are
- /// allocated from a sheaf via [`Sheaf::alloc`]. The cache itself has no
- /// constructor. The initializer should set all fields to their default or
- /// initial values.
+ /// The initializer is applied to newly allocated objects when they are allocated from a sheaf
+ /// via [`Sheaf::alloc`]. The initializer should set all fields to their default or initial
+ /// values.
fn init() -> impl Init<T, Infallible>;
}
+/// Marker type for sheaves from static caches.
+///
+/// Used as a type parameter for [`Sheaf`] to indicate the sheaf was created
+/// from a `&'static KMemCache<T>`.
+pub enum Static {}
+
+/// Marker type for sheaves from dynamic caches.
+///
+/// Used as a type parameter for [`Sheaf`] to indicate the sheaf was created
+/// from a [`KMemCacheHandle`] via [`ArcBorrow`].
+pub enum Dynamic {}
+
+/// A sheaf from a static cache.
+///
+/// This is a [`Sheaf`] backed by a `&'static KMemCache<T>`.
+pub type StaticSheaf<'a, T> = Sheaf<'a, T, Static>;
+
+/// A sheaf from a dynamic cache.
+///
+/// This is a [`Sheaf`] backed by a reference-counted [`KMemCacheHandle`].
+pub type DynamicSheaf<'a, T> = Sheaf<'a, T, Dynamic>;
+
/// A pre-filled container of slab objects.
///
/// A sheaf holds a set of pre-allocated objects from a [`KMemCache`].
@@ -297,23 +440,43 @@ pub trait KMemCacheInit<T> {
///
/// Sheaves provide faster allocation than direct allocation because they use
/// local locks with preemption disabled rather than atomic operations. Note
-/// that each [`SBox`] allocated from a sheaf holds a reference to the cache
-/// the sheaf was created from, to keep the cache alive until the object is
-/// freed. [`Sheaf::alloc`] thus increments the reference count of the cache,
-/// and dropping the [`SBox`] decrements it. Both are atomic operations on a
-/// counter that is shared by all users of the cache.
+/// that each [`SBox`] allocated from a [`DynamicSheaf`] holds a reference to
+/// the [`KMemCacheHandle`] the sheaf was created from, to keep the cache
+/// alive until the object is freed. [`Sheaf::alloc`] thus increments the
+/// reference count of the handle, and dropping the [`SBox`] decrements it.
+/// Both are atomic operations on a counter that is shared by all users of the
+/// cache.
+///
+/// This does not apply to a [`StaticSheaf`]. A static cache is never
+/// destroyed, so objects allocated from it do not hold a reference and no
+/// reference counting takes place.
+///
+/// # Type parameters
+///
+/// - `'a`: The lifetime of the cache reference the sheaf was created from.
+/// The cache is guaranteed to outlive `'a`.
+/// - `T`: The type of objects in this sheaf.
+/// - `A`: Either [`Static`] or [`Dynamic`], indicating whether the backing
+/// cache is a static reference or a reference-counted handle.
+///
+/// For convenience, [`StaticSheaf`] and [`DynamicSheaf`] type aliases are
+/// provided.
///
/// # Lifecycle
///
-/// Sheaves are created via [`KMemCache::sheaf`] and should be returned to the
-/// allocator when no longer needed via [`Sheaf::return_refill`]. If a sheaf is
-/// simply dropped, it is returned with `GFP_NOWAIT` flags, which may result in
-/// the sheaf being flushed and freed rather than being cached for reuse.
+/// Sheaves are created via [`KMemCache::sheaf`] or [`KMemCacheHandle::sheaf`]
+/// and should be returned to the allocator when no longer needed via
+/// [`Sheaf::return_refill`]. If a sheaf is simply dropped, it is returned with
+/// `GFP_NOWAIT` flags, which may result in the sheaf being flushed and freed
+/// rather than being cached for reuse.
///
-/// A sheaf holds a reference to the [`KMemCache`] it was created from.
-/// Dropping the sheaf may thus drop the last reference to the cache and
-/// destroy the cache, which may sleep. See the `# Context` section of
-/// [`KMemCache`].
+/// A sheaf created from a [`KMemCacheHandle`] holds a reference to the
+/// handle. Dropping the sheaf never drops the last reference to the handle,
+/// and thus never destroys the cache: [`KMemCacheHandle::sheaf`] ties the
+/// lifetime `'a` of the sheaf to the [`ArcBorrow`] it is called on, so the
+/// reference the [`ArcBorrow`] was created from outlives the sheaf. A sheaf
+/// can therefore be dropped in a context where sleeping is not allowed. Note
+/// that this does not extend to [`SBox`] instances allocated from the sheaf.
///
/// # Invariants
///
@@ -321,10 +484,11 @@ pub trait KMemCacheInit<T> {
/// `kmem_cache_prefill_sheaf`.
/// - `cache` is the cache from which this sheaf was created.
/// - `dropped` tracks whether the sheaf has been explicitly returned.
-pub struct Sheaf<T: KMemCacheInit<T>> {
+pub struct Sheaf<'a, T: KMemCacheInit<T>, A> {
sheaf: NonNull<bindings::slab_sheaf>,
- cache: Arc<KMemCache<T>>,
+ cache: CacheRef<T>,
dropped: bool,
+ _p: PhantomData<(&'a KMemCache<T>, A)>,
}
// SAFETY: A prefilled sheaf is exclusively owned by the caller and has no
@@ -332,13 +496,13 @@ pub struct Sheaf<T: KMemCacheInit<T>> {
// does not touch percpu state, and `kmem_cache_return_sheaf` reattaches the
// sheaf to the CPU that is current at return time. Thus the sheaf may be sent
// to another thread if the objects it manages can.
-unsafe impl<T: KMemCacheInit<T> + Send> Send for Sheaf<T> {}
+unsafe impl<T: KMemCacheInit<T> + Send, A> Send for Sheaf<'_, T, A> {}
// NOTE: `Sheaf` is deliberately not `Sync`. The C side mutates sheaf state
// without synchronization, relying on the caller's exclusive ownership. The
// mutable receivers of the methods on `Sheaf` enforce this exclusivity.
-impl<T: KMemCacheInit<T>> Sheaf<T> {
+impl<'a, T: KMemCacheInit<T>, A> Sheaf<'a, T, A> {
#[inline]
fn as_raw(&self) -> *mut bindings::slab_sheaf {
self.sheaf.as_ptr()
@@ -363,6 +527,37 @@ pub fn return_refill(mut self, flags: kernel::alloc::Flags) {
drop(self);
}
+ /// Refills the sheaf to at least the specified size.
+ ///
+ /// Replenishes the sheaf by preallocating objects until it contains at
+ /// least `size` objects. If the sheaf already contains `size` or more
+ /// objects, this is a no-op. In practice, the sheaf is refilled to its
+ /// full capacity.
+ ///
+ /// # Arguments
+ ///
+ /// - `flags`: Allocation flags controlling how memory is obtained.
+ /// - `size`: The minimum number of objects the sheaf should contain after
+ /// refilling. If `size` exceeds the cache's `sheaf_capacity`, the sheaf
+ /// may be replaced with a larger one.
+ ///
+ /// # Errors
+ ///
+ /// Returns an error if the objects could not be allocated. If refilling
+ /// fails, the existing sheaf is left intact.
+ pub fn refill(&mut self, flags: kernel::alloc::Flags, size: usize) -> Result {
+ // SAFETY: `self.cache.as_raw()` returns a valid cache pointer and
+ // `&raw mut self.sheaf` points to a valid sheaf per the type invariants.
+ kernel::error::to_result(unsafe {
+ bindings::kmem_cache_refill_sheaf(
+ self.cache.as_raw(),
+ flags.as_raw(),
+ (&raw mut (self.sheaf)).cast(),
+ size.try_into()?,
+ )
+ })
+ }
+
/// Allocates an object from the sheaf.
///
/// Returns a new [`SBox`] containing an initialized object, or [`None`]
@@ -399,7 +594,7 @@ pub fn alloc(&mut self) -> Option<SBox<T>> {
}
}
-impl<T: KMemCacheInit<T>> Drop for Sheaf<T> {
+impl<'a, T: KMemCacheInit<T>, A> Drop for Sheaf<'a, T, A> {
fn drop(&mut self) {
if !self.dropped {
// SAFETY: `self.cache.as_raw()` and `self.as_raw()` return valid
@@ -416,6 +611,40 @@ fn drop(&mut self) {
}
}
+/// Internal reference to a cache, either static or reference-counted.
+///
+/// # Invariants
+///
+/// - For `CacheRef::Static`: the `NonNull` points to a valid `KMemCache<T>`
+/// with `'static` lifetime, derived from a `&'static KMemCache<T>` reference.
+enum CacheRef<T: KMemCacheInit<T>> {
+ /// A reference-counted handle to a dynamically created cache.
+ Arc(Arc<KMemCacheHandle<T>>),
+ /// A pointer to a static lifetime cache.
+ Static(NonNull<KMemCache<T>>),
+}
+
+impl<T: KMemCacheInit<T>> Clone for CacheRef<T> {
+ fn clone(&self) -> Self {
+ match self {
+ Self::Arc(arg0) => Self::Arc(arg0.clone()),
+ Self::Static(arg0) => Self::Static(*arg0),
+ }
+ }
+}
+
+impl<T: KMemCacheInit<T>> CacheRef<T> {
+ #[inline]
+ fn as_raw(&self) -> *mut bindings::kmem_cache {
+ match self {
+ CacheRef::Arc(handle) => handle.as_raw(),
+ // SAFETY: By type invariant, `ptr` points to a valid `KMemCache<T>`
+ // with `'static` lifetime.
+ CacheRef::Static(ptr) => unsafe { ptr.as_ref() }.as_raw(),
+ }
+ }
+}
+
/// An owned allocation from a cache sheaf.
///
/// `SBox` is similar to `Box` but is backed by a slab cache allocation obtained
@@ -425,10 +654,10 @@ fn drop(&mut self) {
/// The contained `T` is initialized when the `SBox` is returned from alloc and
/// dropped when the `SBox` is dropped.
///
-/// An `SBox` holds a reference to the [`KMemCache`] it was allocated from.
-/// Dropping the `SBox` may thus drop the last reference to the cache and
-/// destroy the cache, which may sleep. See the `# Context` section of
-/// [`KMemCache`].
+/// An `SBox` allocated from a [`KMemCacheHandle`] backed sheaf holds a
+/// reference to the handle. Dropping the `SBox` may thus drop the last
+/// reference to the handle and destroy the cache, which may sleep. See the
+/// `# Context` section of [`KMemCacheHandle`].
///
/// # Invariants
///
@@ -437,7 +666,7 @@ fn drop(&mut self) {
/// - The object remains valid for the lifetime of the `SBox`.
pub struct SBox<T: KMemCacheInit<T>> {
ptr: NonNull<T>,
- cache: Arc<KMemCache<T>>,
+ cache: CacheRef<T>,
}
// SAFETY: `SBox<T>` owns a `T`. Sheaf allocated objects are ordinary slab
@@ -449,6 +678,56 @@ unsafe impl<T: KMemCacheInit<T> + Send> Send for SBox<T> {}
// threads only shares `&T`.
unsafe impl<T: KMemCacheInit<T> + Sync> Sync for SBox<T> {}
+impl<T: KMemCacheInit<T>> SBox<T> {
+ /// Consumes the `SBox` and returns the raw pointer to the contained value.
+ ///
+ /// The caller becomes responsible for freeing the memory. The object is not
+ /// dropped and remains initialized. Use [`static_from_ptr`] to reconstruct
+ /// an `SBox` from the pointer.
+ ///
+ /// This method is only intended for objects allocated from a static cache.
+ /// Calling it on an `SBox` backed by a [`KMemCacheHandle`] leaks a
+ /// reference on the handle, preventing the cache from ever being
+ /// destroyed, as [`static_from_ptr`] cannot restore the reference.
+ ///
+ /// [`static_from_ptr`]: SBox::static_from_ptr
+ pub fn into_ptr(self) -> *mut T {
+ debug_assert!(matches!(self.cache, CacheRef::Static(_)));
+ let ptr = self.ptr.as_ptr();
+ core::mem::forget(self);
+ ptr
+ }
+
+ /// Reconstructs an `SBox` from a raw pointer and cache.
+ ///
+ /// This is intended for use with objects that were previously converted to
+ /// raw pointers via [`into_ptr`], typically for passing through C code.
+ ///
+ /// [`into_ptr`]: SBox::into_ptr
+ ///
+ /// # Safety
+ ///
+ /// - `cache` must be a valid pointer to the `kmem_cache` from which `value`
+ /// was allocated.
+ /// - `cache` must be a statically allocated cache that is never destroyed.
+ /// - `value` must be a valid pointer to an initialized `T` that was
+ /// allocated from `cache`.
+ /// - The caller must ensure that no other `SBox` or reference exists for
+ /// `value`.
+ pub unsafe fn static_from_ptr(cache: *mut bindings::kmem_cache, value: *mut T) -> Self {
+ // INVARIANT: The caller guarantees `value` points to a valid,
+ // initialized `T` allocated from `cache`.
+ Self {
+ // SAFETY: By function safety requirements, `value` is not null.
+ ptr: unsafe { NonNull::new_unchecked(value) },
+ cache: CacheRef::Static(
+ // SAFETY: By function safety requirements, `cache` is not null.
+ unsafe { NonNull::new_unchecked(cache.cast()) },
+ ),
+ }
+ }
+}
+
impl<T: KMemCacheInit<T>> Deref for SBox<T> {
type Target = T;
--
2.54.0
next prev parent reply other threads:[~2026-11-20 13:11 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-20 13:10 [PATCH v6 00/12] rust: xarray: add entry API with preloading Andreas Hindborg
2026-11-20 13:10 ` [PATCH v6 01/12] rust: xarray: minor formatting fixes Andreas Hindborg
2026-11-20 13:10 ` [PATCH v6 02/12] rust: xarray: add debug format for `StoreError` Andreas Hindborg
2026-11-20 13:10 ` [PATCH v6 03/12] xarray: move xas_result() and xa_zero_to_null() to the header Andreas Hindborg
2026-11-20 13:10 ` [PATCH v6 04/12] rust: xarray: add `XArrayState` Andreas Hindborg
2026-11-20 13:10 ` [PATCH v6 05/12] rust: xarray: simplify `Guard::load` Andreas Hindborg
2026-11-20 13:10 ` [PATCH v6 06/12] rust: xarray: add `find_next` and `find_next_mut` Andreas Hindborg
2026-11-20 13:10 ` [PATCH v6 07/12] rust: xarray: add entry API Andreas Hindborg
2026-11-20 13:10 ` [PATCH v6 08/12] rust: mm: add abstractions for allocating from a `sheaf` Andreas Hindborg
2026-11-20 13:10 ` Andreas Hindborg [this message]
2026-11-20 13:10 ` [PATCH v6 10/12] xarray, radix-tree: enable sheaf support for kmem_cache Andreas Hindborg
2026-11-20 13:10 ` [PATCH v6 11/12] rust: xarray: add preload API Andreas Hindborg
2026-11-20 13:10 ` [PATCH v6 12/12] rust: xarray: document `Guard` lock drop semantics Andreas Hindborg
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261120-xarray-entry-send-v6-9-1f69d7385f70@kernel.org \
--to=a.hindborg@kernel.org \
--cc=acourbot@nvidia.com \
--cc=akpm@linux-foundation.org \
--cc=aliceryhl@google.com \
--cc=bjorn3_gh@protonmail.com \
--cc=boqun@kernel.org \
--cc=cl@gentwo.org \
--cc=dakr@kernel.org \
--cc=daniel.almeida@collabora.com \
--cc=gary@garyguo.net \
--cc=hao.li@linux.dev \
--cc=harry@kernel.org \
--cc=liam@infradead.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=ljs@kernel.org \
--cc=lossin@kernel.org \
--cc=ojeda@kernel.org \
--cc=rientjes@google.com \
--cc=roman.gushchin@linux.dev \
--cc=rust-for-linux@vger.kernel.org \
--cc=tamird@kernel.org \
--cc=tmgross@umich.edu \
--cc=vbabka@kernel.org \
--cc=willy@infradead.org \
--cc=work@onurozkan.dev \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox