slub: clarify kmem_cache_refill_sheaf() failure behavior
Subsystems (2)
Hao Li
reviewerPATCH 1/1 slub: clarify kmem_cache_refill_sheaf() failure behavior
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.
--- mm/slub.c | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-)
mm/slub.c +15 -6
@@ -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)
Signature · 1 line
2.50.1
Quoted 32 lines · Hao Li
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 <[email protected]>---
mm/slub.c | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-)mm/slub.c +3
-6@@ -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.
mm/slub.c void kmem_cache_return_sheaf(struct kmem_cache *s, gfp_t gfp, · line 5022
Quoted 10 lines
mm/slub.c +10
-0+* 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?
Quoted 8 lines
mm/slub.c +2
-0+* +* 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)Signature · 1 line
2.50.1
Signature · 2 lines
Cheers, Harry / Hyeonggon
Hao Li
reviewerQuoted 47 lines · Harry Yoo
Quoted 32 lines · Hao Li
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 <[email protected]>---
mm/slub.c | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-)mm/slub.c +3
-6@@ -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. mm/slub.c void kmem_cache_return_sheaf(struct kmem_cache *s, gfp_t gfp, · line 5022
Quoted 10 lines
mm/slub.c +10
-0+* 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.
Quoted 2 lines
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!
Quoted 13 lines
Quoted 9 lines
mm/slub.c +2
-0+* +* 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)Signature · 1 line
2.50.1Signature · 2 lines
Cheers, Harry / Hyeonggon