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

[Alice Ryhl <aliceryhl@google.com>]

On Mon, Jan 26, 2026 at 03:20:17PM -0500, Liam R. Howlett wrote:
> * Alice Ryhl <aliceryhl@google.com> [260121 04:56]:
> > 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?
> 
> mas_ will return the special entries.
> 
> mtree_ will return NULL on special entries.  I think this is just
> mtree_load().
> 
> If you want to use your own locking and use mas_, then you can filter
> out the special entries yourself.
> 
> If you want to use the normal api, then the special entries are filtered
> for you.
> 
> This way you can mix/match the apis but the noral api still remains
> simple to use - even if there are advanced users that mixed in.
> 
> The idea is that if you're using the advanced interface and storing
> special entries, then you probably want to do something different on
> those entries - at least sometimes.
> 
> > 
> > Like the docs, you use "get" vs "advance" wording here, but I don't
> > think there's any difference behavior-wise? Is one intended?
> 
> On return type, no, there isn't a difference.  The difference is where
> the mas points in the end (mas->offset, mas->index, mas->last).
> 
> If a NULL is encountered bu mas_next(), then we proceed to the next slot
> (which must have a value, if there is a next slot).  So, mas_next() will
> always return the next entry until there is not a next entry - then it
> returns NULL.  Note that mas_next() takes an 'end' value where we'll
> stop advancing slots regardless if there are values.
> 
> If a NULL is encountered by mas_next_range(), then we return the NULL.
> So, in this way, we can move to the next range even if it's NULL.
> 
> I hope this makes the difference more clear?

Yes.

But I guess the docs should still need to be updated? Right now, both of
them say "Can return the zero entry.", but one of them can't because it
skips them.

Alice