In the in-place refill case, some objects may already have been added
before the function returns -ENOMEM.
Clarify this behavior and polish the rest of the comment for readability.

Signed-off-by: Hao Li <hao.li@linux.dev>
---
Thanks Harry for suggestions on v1!
---
 mm/slub.c | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/mm/slub.c b/mm/slub.c
index 4927407c9699..a45eb1bd2ce5 100644
--- a/mm/slub.c
+++ b/mm/slub.c
@@ -5120,12 +5120,15 @@ 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
+ * Return: 0 on success. The sheaf will contain at least @size objects.
+ * The sheaf might be replaced with a new one if more than sheaf->capacity
+ * objects are requested.
+ *
+ * Return: -ENOMEM on failure. The refill might partially fill the existing
+ * sheaf or leave it unchanged, but it will not replace the existing sheaf.
  *
  * In practice we always refill to full sheaf's capacity.
  */
-- 
2.50.1

On Tue, Apr 07, 2026 at 05:59:10PM +0800, Hao Li wrote:
> In the in-place refill case, some objects may already have been added
> before the function returns -ENOMEM.
> Clarify this behavior and polish the rest of the comment for readability.
> 
> Signed-off-by: Hao Li <hao.li@linux.dev>
> ---
> Thanks Harry for suggestions on v1!

You're welcome!

Overall looks good to me, so:
Acked-by: Harry Yoo (Oracle) <harry@kernel.org>

With some small nitpicking :)

> ---
>  mm/slub.c | 13 ++++++++-----
>  1 file changed, 8 insertions(+), 5 deletions(-)
> 
> diff --git a/mm/slub.c b/mm/slub.c
> index 4927407c9699..a45eb1bd2ce5 100644
> --- a/mm/slub.c
> +++ b/mm/slub.c
> @@ -5120,12 +5120,15 @@ 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
> + * Return: 0 on success. The sheaf will contain at least @size objects.
> + * The sheaf might be replaced with a new one if more than sheaf->capacity

nit: "The sheaf might have been replaced with a new one" ...

> + * objects are requested.
> + *
> + * Return: -ENOMEM on failure. The refill might partially fill the existing
nit:			      ..."Some objects might have been added to the sheaf,
      but the sheaf will not be replaced."

sounds a little bit more clear (tm).

> + * sheaf or leave it unchanged, but it will not replace the existing sheaf.
>   *
>   * In practice we always refill to full sheaf's capacity.
>   */
> -- 
> 2.50.1
> 

-- 
Cheers,
Harry / Hyeonggon

On Tue, Apr 07, 2026 at 07:49:39PM +0900, Harry Yoo (Oracle) wrote:
> On Tue, Apr 07, 2026 at 05:59:10PM +0800, Hao Li wrote:
> > In the in-place refill case, some objects may already have been added
> > before the function returns -ENOMEM.
> > Clarify this behavior and polish the rest of the comment for readability.
> > 
> > Signed-off-by: Hao Li <hao.li@linux.dev>
> > ---
> > Thanks Harry for suggestions on v1!
> 
> You're welcome!
> 
> Overall looks good to me, so:
> Acked-by: Harry Yoo (Oracle) <harry@kernel.org>
> 
> With some small nitpicking :)

Thanks for pointing that out :)

> 
> > ---
> >  mm/slub.c | 13 ++++++++-----
> >  1 file changed, 8 insertions(+), 5 deletions(-)
> > 
> > diff --git a/mm/slub.c b/mm/slub.c
> > index 4927407c9699..a45eb1bd2ce5 100644
> > --- a/mm/slub.c
> > +++ b/mm/slub.c
> > @@ -5120,12 +5120,15 @@ 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
> > + * Return: 0 on success. The sheaf will contain at least @size objects.
> > + * The sheaf might be replaced with a new one if more than sheaf->capacity
> 
> nit: "The sheaf might have been replaced with a new one" ...

Yes, the perfect tense would be better.
> 
> > + * objects are requested.
> > + *
> > + * Return: -ENOMEM on failure. The refill might partially fill the existing
> nit:			      ..."Some objects might have been added to the sheaf,
>       but the sheaf will not be replaced."

Great! this is less ambiguous than "leave it unchanged."

> 
> sounds a little bit more clear (tm).
> 
> > + * sheaf or leave it unchanged, but it will not replace the existing sheaf.
> >   *
> >   * In practice we always refill to full sheaf's capacity.
> >   */
> > -- 
> > 2.50.1
> > 
> 

-- 
Thanks,
Hao