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

[Alice Ryhl <aliceryhl@google.com>]

On Sat, Feb 07, 2026 at 08:16:56AM +0000, Liam R. Howlett wrote:
> * Alice Ryhl <aliceryhl@google.com> [260204 15:29]:
> > 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.
> 
> Neither of the ones you are updating should skip the zero entry as they
> are both the advanced interface.

What do you call the entries that mas_next() skips? You know, the ones
where it would otherwise return NULL.

Alice