maple_tree: document that "last" in mtree_insert_range() is inclusive
Subsystems (3)
PATCH 1/1 maple_tree: document that "last" in mtree_insert_range() is inclusive
From: Steven Rostedt <[email protected]>
The kernel doc of mtree_insert_range() does not state if the address represented by the "last" parameter is inclusive or exclusive. This can lead to bugs by code that assumes it is exclusive. Explicitly state that the parameter is inclusive, and add '[' and ']' around the word "end" to also stress this point.
--- lib/maple_tree.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
lib/maple_tree.c +3 -1
@@ -5730,10 +5730,12 @@ EXPORT_SYMBOL(mtree_store);* mtree_insert_range() - Insert an entry at a given range if there is no value. * @mt: The maple tree * @first: The start of the range -* @last: The end of the range +* @last: The [end] of the range * @entry: The entry to store * @gfp: The GFP_FLAGS to use for allocations. * +* Note that @last is inclusive. That is, @last = @first + length - 1; +* * Return: 0 on success, -EEXISTS if the range is occupied, -EINVAL on invalid * request, -ENOMEM if memory could not be allocated. */
Signature · 1 line
2.53.0
Quoted 9 lines · Steven Rostedt
From: Steven Rostedt <[email protected]>
The kernel doc of
mtree_insert_range()does not state if the address represented by the "last" parameter is inclusive or exclusive. This can lead to bugs by code that assumes it is exclusive. Explicitly state that the parameter is inclusive, and add '[' and ']' around the word "end" to also stress this point.Signed-off-by Steven Rostedt <[email protected]>
Quoted 8 lines
lib/maple_tree.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)lib/maple_tree.c +0
-0
lib/maple_tree.c EXPORT_SYMBOL(mtree_store); · line 5737
Quoted 9 lines
lib/maple_tree.c +2
-1@@ -5730,10 +5730,12 @@ EXPORT_SYMBOL(mtree_store);* mtree_insert_range() - Insert an entry at a given range if there is no value. * @mt: The maple tree * @first: The start of the range -* @last: The end of the range +* @last: The [end] of the range * @entry: The entry to store * @gfp: The GFP_FLAGS to use for allocations. * +* Note that @last is inclusive. That is, @last = @first + length - 1;
How about writing it like this?
* @first: The start of the range
* @last: The end of the range (inclusive)
Alice
Liam R. Howlett
maintainerQuoted 33 lines · Alice Ryhl
Quoted 9 lines · Steven Rostedt
From: Steven Rostedt <[email protected]>
The kernel doc of
mtree_insert_range()does not state if the address represented by the "last" parameter is inclusive or exclusive. This can lead to bugs by code that assumes it is exclusive. Explicitly state that the parameter is inclusive, and add '[' and ']' around the word "end" to also stress this point.Signed-off-by Steven Rostedt <[email protected]>Reviewed-by Alice Ryhl <[email protected]>Quoted 8 lines
lib/maple_tree.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)lib/maple_tree.c +0
-0lib/maple_tree.c EXPORT_SYMBOL(mtree_store); · line 5737
Quoted 9 lines
lib/maple_tree.c +2
-1@@ -5730,10 +5730,12 @@ EXPORT_SYMBOL(mtree_store);* mtree_insert_range() - Insert an entry at a given range if there is no value. * @mt: The maple tree * @first: The start of the range -* @last: The end of the range +* @last: The [end] of the range * @entry: The entry to store * @gfp: The GFP_FLAGS to use for allocations. * +* Note that @last is inclusive. That is, @last = @first + length - 1; How about writing it like this?
Quoted 2 lines
* @first: The start of the range
* @last: The end of the range (inclusive)
I like this.
I think the range should be identified in the initial statement. Something like this:
mtree_insert_range() - Insert an entry from [first, last] if there isn't an entry within that range.
Quoted 7 lines
Alice
Signature · 3 lines
maple-tree mailing list [email protected] https://lists.infradead.org/mailman/listinfo/maple-tree
Quoted 34 lines · On Fri, 8 May 2026 22:51:51 +0200 "Liam R. Howlett" <[email protected]> wrote:
Quoted 33 lines · Alice Ryhl
Quoted 9 lines · Steven Rostedt
From: Steven Rostedt <[email protected]>
The kernel doc of
mtree_insert_range()does not state if the address represented by the "last" parameter is inclusive or exclusive. This can lead to bugs by code that assumes it is exclusive. Explicitly state that the parameter is inclusive, and add '[' and ']' around the word "end" to also stress this point.Signed-off-by Steven Rostedt <[email protected]>Reviewed-by Alice Ryhl <[email protected]>Quoted 8 lines
lib/maple_tree.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)lib/maple_tree.c +0
-0lib/maple_tree.c EXPORT_SYMBOL(mtree_store); · line 5737
Quoted 9 lines
lib/maple_tree.c +2
-1@@ -5730,10 +5730,12 @@ EXPORT_SYMBOL(mtree_store);* mtree_insert_range() - Insert an entry at a given range if there is no value. * @mt: The maple tree * @first: The start of the range -* @last: The end of the range +* @last: The [end] of the range * @entry: The entry to store * @gfp: The GFP_FLAGS to use for allocations. * +* Note that @last is inclusive. That is, @last = @first + length - 1; How about writing it like this?
Quoted 5 lines
Quoted 2 lines
* @first: The start of the range
* @last: The end of the range (inclusive)I like this.
+1. I'm also wondering if it make sense to add '(inclusive)' for 'first', too.
Quoted 6 lines
I think the range should be identified in the initial statement. Something like this:
mtree_insert_range()- Insert an entry from [first, last] if there isn't an entry within that range.
+1.
Thanks,
SJ
[...]
Quoted 7 lines · SeongJae Park
Quoted 5 lines
Quoted 2 lines
* @first: The start of the range
* @last: The end of the range (inclusive)I like this.
+1. I'm also wondering if it make sense to add '(inclusive)' for 'first', too.
I can't think of a situation in computing where we use an exclusive-first. Pure mathematics, yes, we might want to express a range as (1,2) to exclude both 1 and 2 but include 1+epsilon for all epsilon > 0. Maybe I don't work with floating point numbers enough, but I've never seen a kernel programmer make an off-by-one with the start of a range. End-of-the-range is all too common.
Quoted 7 lines · On Sat, 9 May 2026 09:31:13 +0100 Matthew Wilcox <[email protected]> wrote:
Quoted 6 lines · SeongJae Park
Quoted 5 lines
Quoted 2 lines
* @first: The start of the range
* @last: The end of the range (inclusive)I like this.
Quoted 8 lines
Quoted 1 line
+1. I'm also wondering if it make sense to add '(inclusive)' for 'first', too.
I can't think of a situation in computing where we use an exclusive-first. Pure mathematics, yes, we might want to express a range as (1,2) to exclude both 1 and 2 but include 1+epsilon for all epsilon > 0. Maybe I don't work with floating point numbers enough, but I've never seen a kernel programmer make an off-by-one with the start of a range. End-of-the-range is all too common.
Makes sense, thank you for sharing your thought for my silly question!
Thanks,
SJ