[v2] maple_tree: document that "last" in mtree_insert_range() is inclusive

[PATCH v2] maple_tree: document that "last" in mtree_insert_range() is inclusive

Posted by Steven Rostedt 1 month ago

From: Steven Rostedt <rostedt@goodmis.org>

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.

Signed-off-by: Steven Rostedt <rostedt@goodmis.org>
---
Changes since v1: https://patch.msgid.link/20260506105218.2d027cc0@fedora

- Use "(inclusive)" instead of adding '[' ']' around "end". (Alice Ryhl)

- Add "from [first, last]" in the short description. (Liam Howlett)

 lib/maple_tree.c | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/lib/maple_tree.c b/lib/maple_tree.c
index d18d7ed9ab67..7f6c9b729a1a 100644
--- a/lib/maple_tree.c
+++ b/lib/maple_tree.c
@@ -5727,13 +5727,16 @@ int mtree_store(struct maple_tree *mt, unsigned long index, void *entry,
 EXPORT_SYMBOL(mtree_store);
 
 /**
- * mtree_insert_range() - Insert an entry at a given range if there is no value.
+ * mtree_insert_range() - Insert an entry from [first, last] 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 (inclusive)
  * @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.
  */
-- 
2.53.0

Re: [PATCH v2] maple_tree: document that "last" in mtree_insert_range() is inclusive

Posted by SeongJae Park 4 weeks, 1 day ago

On Tue, 12 May 2026 17:56:23 -0400 Steven Rostedt <rostedt@kernel.org> wrote:

> From: Steven Rostedt <rostedt@goodmis.org>
> 
> 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.
> 
> Signed-off-by: Steven Rostedt <rostedt@goodmis.org>

Acked-by: SeongJae Park <sj@kernel.org>

> ---
> Changes since v1: https://patch.msgid.link/20260506105218.2d027cc0@fedora
> 
> - Use "(inclusive)" instead of adding '[' ']' around "end". (Alice Ryhl)
> 
> - Add "from [first, last]" in the short description. (Liam Howlett)
> 
>  lib/maple_tree.c | 7 +++++--
>  1 file changed, 5 insertions(+), 2 deletions(-)
> 
> diff --git a/lib/maple_tree.c b/lib/maple_tree.c
> index d18d7ed9ab67..7f6c9b729a1a 100644
> --- a/lib/maple_tree.c
> +++ b/lib/maple_tree.c
> @@ -5727,13 +5727,16 @@ int mtree_store(struct maple_tree *mt, unsigned long index, void *entry,
>  EXPORT_SYMBOL(mtree_store);
>  
>  /**
> - * mtree_insert_range() - Insert an entry at a given range if there is no value.
> + * mtree_insert_range() - Insert an entry from [first, last] at a given range
> + *                        if there is no value.

It feels "at a given range" bit repetitive to me.  s/at a given range// ?


Thanks,
SJ

[...]

Re: [PATCH v2] maple_tree: document that "last" in mtree_insert_range() is inclusive

Posted by Steven Rostedt 4 weeks, 1 day ago

On Wed, 13 May 2026 18:42:04 -0700
SeongJae Park <sj@kernel.org> wrote:

> >  /**
> > - * mtree_insert_range() - Insert an entry at a given range if there is no value.
> > + * mtree_insert_range() - Insert an entry from [first, last] at a given range
> > + *                        if there is no value.  
> 
> It feels "at a given range" bit repetitive to me.  s/at a given range// ?
> 

I just added what Liam suggested. Should I send a v3?

-- Steve

Re: [PATCH v2] maple_tree: document that "last" in mtree_insert_range() is inclusive

Posted by SeongJae Park 4 weeks, 1 day ago

On Thu, 14 May 2026 10:07:23 -0400 Steven Rostedt <rostedt@kernel.org> wrote:

> On Wed, 13 May 2026 18:42:04 -0700
> SeongJae Park <sj@kernel.org> wrote:
> 
> > >  /**
> > > - * mtree_insert_range() - Insert an entry at a given range if there is no value.
> > > + * mtree_insert_range() - Insert an entry from [first, last] at a given range
> > > + *                        if there is no value.  
> > 
> > It feels "at a given range" bit repetitive to me.  s/at a given range// ?
> > 
> 
> I just added what Liam suggested.

Liam's suggestion was very sligtly different.

: Something like this:
:
: mtree_insert_range() - Insert an entry from [first, last] if there isn't
: an entry within that range.

So I assumed you intentionally reworded it, but might forgot erasing 'at a
given range'.  English is never my mother tongue language, but Geminit also
told me dropping 'at a given range' makes it bit easier to read.  Hence I just
wanted to check if this is intentional.

> Should I send a v3?

The current wording works for me.  English is never my mother tongue langauage,
so I cannot judge.  I just wanted to make sure this is the intended change.  So
I will leave the decision to you and others.

If we decide to rewording, I think Andrew could help without asking you to
resned v3 for such a minor change.

Thanks,
SJ

[...]

Re: [PATCH v2] maple_tree: document that "last" in mtree_insert_range() is inclusive

Posted by Liam R. Howlett 4 weeks ago

On 26/05/14 07:23AM, SeongJae Park wrote:
> On Thu, 14 May 2026 10:07:23 -0400 Steven Rostedt <rostedt@kernel.org> wrote:
> 
> > On Wed, 13 May 2026 18:42:04 -0700
> > SeongJae Park <sj@kernel.org> wrote:
> > 
> > > >  /**
> > > > - * mtree_insert_range() - Insert an entry at a given range if there is no value.
> > > > + * mtree_insert_range() - Insert an entry from [first, last] at a given range
> > > > + *                        if there is no value.  
> > > 
> > > It feels "at a given range" bit repetitive to me.  s/at a given range// ?
> > > 
> > 
> > I just added what Liam suggested.
> 
> Liam's suggestion was very sligtly different.
> 
> : Something like this:
> :
> : mtree_insert_range() - Insert an entry from [first, last] if there isn't
> : an entry within that range.
> 
> So I assumed you intentionally reworded it, but might forgot erasing 'at a
> given range'.  English is never my mother tongue language, but Geminit also
> told me dropping 'at a given range' makes it bit easier to read.  Hence I just
> wanted to check if this is intentional.
> 
> > Should I send a v3?
> 
> The current wording works for me.  English is never my mother tongue langauage,
> so I cannot judge.  I just wanted to make sure this is the intended change.  So
> I will leave the decision to you and others.
> 
> If we decide to rewording, I think Andrew could help without asking you to
> resned v3 for such a minor change.
> 

I'm happy with what we have.  Steven, since it wasn't clear to you
before maybe you can say if it's clear now?

I think I'll have to look through the rest of the function documentation
to align to what we've decided here.

Thanks,
Liam

Re: [PATCH v2] maple_tree: document that "last" in mtree_insert_range() is inclusive

Posted by Steven Rostedt 4 weeks ago

On Fri, 15 May 2026 09:35:25 -0400
"Liam R. Howlett" <liam@infradead.org> wrote:

> I'm happy with what we have.  Steven, since it wasn't clear to you
> before maybe you can say if it's clear now?

Well, since I wrote the update, it had better be clear for me now! ;-)

-- Steve

Re: [PATCH v2] maple_tree: document that "last" in mtree_insert_range() is inclusive

Posted by Liam R. Howlett 1 month ago

On 26/05/12 05:56PM, Steven Rostedt wrote:
> From: Steven Rostedt <rostedt@goodmis.org>
> 
> 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.
> 
> Signed-off-by: Steven Rostedt <rostedt@goodmis.org>

Thanks, this looks good.

Reviewed-by: "Liam R. Howlett" <liam@infradead.org>

> ---
> Changes since v1: https://patch.msgid.link/20260506105218.2d027cc0@fedora
> 
> - Use "(inclusive)" instead of adding '[' ']' around "end". (Alice Ryhl)
> 
> - Add "from [first, last]" in the short description. (Liam Howlett)
> 
>  lib/maple_tree.c | 7 +++++--
>  1 file changed, 5 insertions(+), 2 deletions(-)
> 
> diff --git a/lib/maple_tree.c b/lib/maple_tree.c
> index d18d7ed9ab67..7f6c9b729a1a 100644
> --- a/lib/maple_tree.c
> +++ b/lib/maple_tree.c
> @@ -5727,13 +5727,16 @@ int mtree_store(struct maple_tree *mt, unsigned long index, void *entry,
>  EXPORT_SYMBOL(mtree_store);
>  
>  /**
> - * mtree_insert_range() - Insert an entry at a given range if there is no value.
> + * mtree_insert_range() - Insert an entry from [first, last] 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 (inclusive)
>   * @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.
>   */
> -- 
> 2.53.0
> 
> 
> -- 
> maple-tree mailing list
> maple-tree@lists.infradead.org
> https://lists.infradead.org/mailman/listinfo/maple-tree