Re: [PATCH] maple_tree: update mas_next[_range] docs

["Liam R. Howlett" <Liam.Howlett@oracle.com>]

* Alice Ryhl <aliceryhl@google.com> [260118 06:00]:
> If you read the docs, it sounds like the difference between these
> functions is whether mas->index and mas->last are updated. However, if
> you read the implementation, you will instead find that the difference
> is whether NULL entries are skipped.

This is not the intent.

mas_ should return special values including the XA_ZERO_ENTRY.

mas_next() should get the next non-NULL value.

mas_next_range() should advance the maple state to the next range,
regardless of what is in the range (NULL, special, or a regular entry).

Both should update the mas->index and mas->last values, if it moves
(ie, no error state is encountered).

> 
> Signed-off-by: Alice Ryhl <aliceryhl@google.com>
> ---
>  lib/maple_tree.c | 10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/lib/maple_tree.c b/lib/maple_tree.c
> index 5aa4c95000188d3ba461418e09445be78098578e..fe0f0440cd84e7a0fe946d5371e651d153f40d21 100644
> --- a/lib/maple_tree.c
> +++ b/lib/maple_tree.c
> @@ -5293,13 +5293,14 @@ static bool mas_next_setup(struct ma_state *mas, unsigned long max,
>  }
>  
>  /**
> - * mas_next() - Get the next entry.
> + * mas_next() - Advance the maple state to the next range, skipping zero entries.
>   * @mas: The maple state
>   * @max: The maximum index to check.
>   *
>   * Returns the next entry after @mas->index.
> + * Updates @mas->index and @mas->last to the range.
>   * Must hold rcu_read_lock or the write lock.
> - * Can return the zero entry.
> + * Skips entries reserved with XA_ZERO_ENTRY.
>   *
>   * Return: The next entry or %NULL
>   */
> @@ -5316,11 +5317,12 @@ void *mas_next(struct ma_state *mas, unsigned long max)
>  EXPORT_SYMBOL_GPL(mas_next);
>  
>  /**
> - * mas_next_range() - Advance the maple state to the next range
> + * mas_next_range() - Advance the maple state to the next range.
>   * @mas: The maple state
>   * @max: The maximum index to check.
>   *
> - * Sets @mas->index and @mas->last to the range.
> + * Returns the next entry after @mas->index.
> + * Updates @mas->index and @mas->last to the range.
>   * Must hold rcu_read_lock or the write lock.
>   * Can return the zero entry.
>   *
> 
> ---
> base-commit: 8f0b4cce4481fb22653697cced8d0d04027cb1e8
> change-id: 20260118-mas-next-doc-20171df817bd
> 
> Best regards,
> -- 
> Alice Ryhl <aliceryhl@google.com>
>