slub: clarify kmem_cache_refill_sheaf() comments
Subsystems (2)
Hao Li
reviewerPATCH v2 1/1 slub: clarify kmem_cache_refill_sheaf() comments
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.
---
Thanks Harry for suggestions on v1!
--- mm/slub.c | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-)
mm/slub.c +8 -5
@@ -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. */
Signature · 1 line
2.50.1
Quoted 7 lines · Hao Li
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 <[email protected]>---
Thanks Harry for suggestions on v1!
You're welcome!
Overall looks good to me, so:
With some small nitpicking :)
Quoted 12 lines
--- mm/slub.c | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-)mm/slub.c +0
-0@@ -5120,12 +5120,15 @@ void kmem_cache_return_sheaf(struct kmem_cache *s, gfp_t gfp, }/*
mm/slub.c void kmem_cache_return_sheaf(struct kmem_cache *s, gfp_t gfp, · line 5127
Quoted 10 lines
mm/slub.c +4
-5-* 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" ...
mm/slub.c void kmem_cache_return_sheaf(struct kmem_cache *s, gfp_t gfp, · line 5130
Quoted 3 lines
mm/slub.c +3
-0+* 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).
Quoted 7 lines
mm/slub.c +1
-0+* sheaf or leave it unchanged, but it will not replace the existing sheaf. * * In practice we always refill to full sheaf's capacity. */ Signature · 1 line
2.50.1
Signature · 2 lines
Cheers, Harry / Hyeonggon
Hao Li
reviewerQuoted 9 lines · Harry Yoo (Oracle)
Quoted 7 lines · Hao Li
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 <[email protected]>---
Thanks Harry for suggestions on v1!
Quoted 6 lines
You're welcome!
Overall looks good to me, so:
With some small nitpicking :)
Thanks for pointing that out :)
Quoted 12 lines
Quoted 12 lines
--- mm/slub.c | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-)mm/slub.c +0
-0@@ -5120,12 +5120,15 @@ void kmem_cache_return_sheaf(struct kmem_cache *s, gfp_t gfp, }
Quoted 13 lines
mm/slub.c void kmem_cache_return_sheaf(struct kmem_cache *s, gfp_t gfp, · line 5127
Quoted 11 lines
mm/slub.c +4
-5/* -* 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.
Quoted 6 lines
mm/slub.c void kmem_cache_return_sheaf(struct kmem_cache *s, gfp_t gfp, · line 5130
Quoted 4 lines
mm/slub.c +3
-0+* 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."
Quoted 11 lines
sounds a little bit more clear (tm).
Quoted 7 lines
mm/slub.c +1
-0+* sheaf or leave it unchanged, but it will not replace the existing sheaf. * * In practice we always refill to full sheaf's capacity. */ Signature · 1 line
2.50.1
Signature · 2 lines
Thanks, Hao