Skip to contentSkip to conversation

slub: clarify kmem_cache_refill_sheaf() comments

PATCH Superseded Hao Li 2 participants 3 messages Apr 7

Subsystems (2)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Hao Li

author reviewer
#0 lore raw

PATCH 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
index 4927407c9699..a45eb1bd2ce5 100644
@@ -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
maintainer Acked-by on v2 1/1
#1 lore raw
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.

---
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
index 4927407c9699..a45eb1bd2ce5 100644
@@ -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
author reviewer
#2 lore raw
Quoted 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.

---
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
index 4927407c9699..a45eb1bd2ce5 100644
@@ -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