Skip to contentSkip to conversation

slub: clarify kmem_cache_refill_sheaf() failure behavior

PATCH In review Hao Li 2 participants 3 messages Mar 12 – Mar 14

Subsystems (2)
lore
Share & tools
lore

Hao Li

author reviewer
#0 lore raw

PATCH 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
index 11a99bd06ac7..8ae248b5b384 100644
@@ -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
#1 lore raw
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.

---

 mm/slub.c | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)
mm/slub.c +3 -6
index 11a99bd06ac7..8ae248b5b384 100644
@@ -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
author reviewer
#2 lore raw
Quoted 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.

---

 mm/slub.c | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)
mm/slub.c +3 -6
index 11a99bd06ac7..8ae248b5b384 100644
@@ -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.1
Signature · 2 lines
Cheers,
Harry / Hyeonggon