kmem_cache_refill_sheaf() can fail in two slightly different ways.
During an in-place refill, some objects may already have been added
before the function returns -ENOMEM. On the other hand, if allocation of
a larger replacement sheaf fails, the original sheaf remains unchanged.

Update the comment to spell out both cases explicitly for clarity.

Signed-off-by: Hao Li <hao.li@linux.dev>
---
 mm/slub.c | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/mm/slub.c b/mm/slub.c
index 11a99bd06ac7..8ae248b5b384 100644
--- a/mm/slub.c
+++ b/mm/slub.c
@@ -5005,14 +5005,23 @@ void kmem_cache_return_sheaf(struct kmem_cache *s, gfp_t gfp,
 }
 
 /*
- * refill a sheaf previously returned by kmem_cache_prefill_sheaf to at least
- * the given size
+ * Refill a sheaf previously returned by kmem_cache_prefill_sheaf to at least
+ * the given size.
  *
- * the sheaf might be replaced by a new one when requesting more than
- * s->sheaf_capacity objects if such replacement is necessary, but the refill
- * fails (returning -ENOMEM), the existing sheaf is left intact
+ * On success, the sheaf will contain at least @size objects.
  *
- * In practice we always refill to full sheaf's capacity.
+ * On failure, there are two cases:
+ *
+ *     1. If the requested size fits within the current sheaf's capacity, the
+ *     refill is done in place. In that case, a failed refill may still fill
+ *     some additional objects into the existing sheaf before returning -ENOMEM.
+ *
+ *     2. If the requested size exceeds the current sheaf's capacity, a new
+ *     larger sheaf may be allocated to replace the original one. In that case,
+ *     if allocation of the replacement sheaf fails, the original sheaf is left
+ *     unchanged.
+ *
+ * In practice we usually refill to the sheaf's full capacity.
  */
 int kmem_cache_refill_sheaf(struct kmem_cache *s, gfp_t gfp,
 			    struct slab_sheaf **sheafp, unsigned int size)
-- 
2.50.1

On Thu, Mar 12, 2026 at 07:42:25PM +0800, Hao Li wrote:
> kmem_cache_refill_sheaf() can fail in two slightly different ways.
> During an in-place refill, some objects may already have been added
> before the function returns -ENOMEM. On the other hand, if allocation of
> a larger replacement sheaf fails, the original sheaf remains unchanged.
> 
> Update the comment to spell out both cases explicitly for clarity.
> 
> Signed-off-by: Hao Li <hao.li@linux.dev>
> ---
>
>  mm/slub.c | 21 +++++++++++++++------
>  1 file changed, 15 insertions(+), 6 deletions(-)
> 
> diff --git a/mm/slub.c b/mm/slub.c
> index 11a99bd06ac7..8ae248b5b384 100644
> --- a/mm/slub.c
> +++ b/mm/slub.c
> @@ -5005,14 +5005,23 @@ void kmem_cache_return_sheaf(struct kmem_cache *s, gfp_t gfp,
>  }
>  
>  /*
> - * refill a sheaf previously returned by kmem_cache_prefill_sheaf to at least
> - * the given size
> + * Refill a sheaf previously returned by kmem_cache_prefill_sheaf to at least
> + * the given size.
>   *
> - * the sheaf might be replaced by a new one when requesting more than
> - * s->sheaf_capacity objects if such replacement is necessary, but the refill
> - * fails (returning -ENOMEM), the existing sheaf is left intact
> + * On success, the sheaf will contain at least @size objects.
>   *
> - * In practice we always refill to full sheaf's capacity.
> + * On failure, there are two cases:
> + *
> + *     1. If the requested size fits within the current sheaf's capacity, the
> + *     refill is done in place. In that case, a failed refill may still fill
> + *     some additional objects into the existing sheaf before returning -ENOMEM.
> + *
> + *     2. If the requested size exceeds the current sheaf's capacity, a new
> + *     larger sheaf may be allocated to replace the original one. In that case,
> + *     if allocation of the replacement sheaf fails, the original sheaf is left
> + *     unchanged.

This is correct, but users of this API probably don't need to know the
implementation in detail.

I think it's fine to simply say the sheaf may have additional objects even
on failure?

> + *
> + * In practice we usually refill to the sheaf's full capacity.
>   */
>  int kmem_cache_refill_sheaf(struct kmem_cache *s, gfp_t gfp,
>  			    struct slab_sheaf **sheafp, unsigned int size)
> -- 
> 2.50.1
> 

-- 
Cheers,
Harry / Hyeonggon

On Fri, Mar 13, 2026 at 09:36:22PM +0900, Harry Yoo wrote:
> On Thu, Mar 12, 2026 at 07:42:25PM +0800, Hao Li wrote:
> > kmem_cache_refill_sheaf() can fail in two slightly different ways.
> > During an in-place refill, some objects may already have been added
> > before the function returns -ENOMEM. On the other hand, if allocation of
> > a larger replacement sheaf fails, the original sheaf remains unchanged.
> > 
> > Update the comment to spell out both cases explicitly for clarity.
> > 
> > Signed-off-by: Hao Li <hao.li@linux.dev>
> > ---
> >
> >  mm/slub.c | 21 +++++++++++++++------
> >  1 file changed, 15 insertions(+), 6 deletions(-)
> > 
> > diff --git a/mm/slub.c b/mm/slub.c
> > index 11a99bd06ac7..8ae248b5b384 100644
> > --- a/mm/slub.c
> > +++ b/mm/slub.c
> > @@ -5005,14 +5005,23 @@ void kmem_cache_return_sheaf(struct kmem_cache *s, gfp_t gfp,
> >  }
> >  
> >  /*
> > - * refill a sheaf previously returned by kmem_cache_prefill_sheaf to at least
> > - * the given size
> > + * Refill a sheaf previously returned by kmem_cache_prefill_sheaf to at least
> > + * the given size.
> >   *
> > - * the sheaf might be replaced by a new one when requesting more than
> > - * s->sheaf_capacity objects if such replacement is necessary, but the refill
> > - * fails (returning -ENOMEM), the existing sheaf is left intact
> > + * On success, the sheaf will contain at least @size objects.
> >   *
> > - * In practice we always refill to full sheaf's capacity.
> > + * On failure, there are two cases:
> > + *
> > + *     1. If the requested size fits within the current sheaf's capacity, the
> > + *     refill is done in place. In that case, a failed refill may still fill
> > + *     some additional objects into the existing sheaf before returning -ENOMEM.
> > + *
> > + *     2. If the requested size exceeds the current sheaf's capacity, a new
> > + *     larger sheaf may be allocated to replace the original one. In that case,
> > + *     if allocation of the replacement sheaf fails, the original sheaf is left
> > + *     unchanged.
> 
> This is correct, but users of this API probably don't need to know the
> implementation in detail.
> 
> I think it's fine to simply say the sheaf may have additional objects even
> on failure?

That makes sense.
Too much explanation could actually distract users.
Thanks!

> 
> > + *
> > + * In practice we usually refill to the sheaf's full capacity.
> >   */
> >  int kmem_cache_refill_sheaf(struct kmem_cache *s, gfp_t gfp,
> >  			    struct slab_sheaf **sheafp, unsigned int size)
> > -- 
> > 2.50.1
> > 
> 
> -- 
> Cheers,
> Harry / Hyeonggon