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

[Alice Ryhl <aliceryhl@google.com>]

On Tue, Jan 20, 2026 at 12:54:47PM -0500, Liam R. Howlett wrote:
> * 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).

I guess I'm a bit confused about the difference between XA_ZERO_ENTRY
and returning NULL. Isn't the case where we return NULL when a slot has
been reserved but not inserted yet?

Like the docs, you use "get" vs "advance" wording here, but I don't
think there's any difference behavior-wise? Is one intended?

Alice