Re: [PATCH v5 07/70] Maple Tree: Add new data structure

[Mike Rapoport <rppt@kernel.org>]

On Thu, Feb 03, 2022 at 02:38:42AM +0000, Liam Howlett wrote:
> * Mike Rapoport <rppt@kernel.org> [220202 12:11]:
> > Hi Liam,
> > 
> > On Wed, Feb 02, 2022 at 02:41:56AM +0000, Liam Howlett wrote:
> > > From: "Liam R. Howlett" <Liam.Howlett@Oracle.com>
> > > 
> > > +The Maple Tree maintains a small memory footprint and was designed to use
> > > +modern processor cache efficiently.  The most important user of the Maple Tree
> > > +is the virtual memory area.
> > 
> > For me it sounds like VMA *is* the maple tree user. Maybe
> > 
> >   The most important usage of the Maple Tree is tracking of the virtual
> >   memory areas.
> > 
> 
> Thanks, I can see that now.  I'm not a fan of either of the ways this is
> written but yours is more clear.

Maybe you can come up with even better one :)
 
> > > diff --git a/include/linux/maple_tree.h b/include/linux/maple_tree.h
> > > new file mode 100644
> > > index 000000000000..14ddeaa8f3e7
> > > --- /dev/null
> > > +++ b/include/linux/maple_tree.h
> > > @@ -0,0 +1,673 @@
> > > +/* SPDX-License-Identifier: GPL-2.0+ */
> > > +#ifndef _LINUX_MAPLE_TREE_H
> > > +#define _LINUX_MAPLE_TREE_H
> > > +/*
> > > + * Maple Tree - An RCU-safe adaptive tree for storing ranges
> > > + * Copyright (c) 2018 Oracle
> > 
> > 2018 - 2022?
> 
> Wait, what happened in 2019-2022?  Did I miss anything?

I'm really not a copyright expert, but from what I see the dates in
copyright notice use the year when the patches are posted or a range that
end in that year.
 
> > 
> > > + * Authors:     Liam R. Howlett <Liam.Howlett@Oracle.com>
> > > + *              Matthew Wilcox <willy@infradead.org>
> > > + */
> > > +
> > > +#include <linux/kernel.h>
> > > +#include <linux/rcupdate.h>
> > > +#include <linux/spinlock.h>
> > > +/* #define CONFIG_MAPLE_RCU_DISABLED */
> > > +/* #define CONFIG_DEBUG_MAPLE_TREE_VERBOSE */
> > > +
> > > +/*
> > > + * Allocated nodes are mutable until they have been inserted into the tree,
> > > + * at which time they cannot change their type until they have been removed
> > > + * from the tree and an RCU grace period has passed.
> > > + *
> > > + * Removed nodes have their ->parent set to point to themselves.  RCU readers
> > > + * check ->parent before relying on the value that they loaded from the
> > > + * slots array.  This lets us reuse the slots array for the RCU head.
> > > + *
> > > + * Nodes in the tree point to their parent unless bit 0 is set.
> > 
> > There are a lots of comments describing the maple tree internals here and
> > below. Did yaou consider adding a section "Implementation details" or
> > something like that to the maple_tree.rst and linking these comments there
> > with DOC: and some glue text?
> 
> I did.  I actually had it in there but moved it into the code in an
> effort to avoid the documentation from being a developer doc.  I'd like
> it to be a user document.  I also did not want the implementation
> details to be too far away from the code to avoid it being missed when
> the code changes.

There could be two documents: one for the users and another one with
implementation details ;-)

The implementation description can then include DOC: parts to keep that
documentation close to the code. But if you prefer to skip this part (like
most of us do) I'll understand :)

> > > +/*
> > > + * More complicated stores can cause two nodes to become one or tree and
> > 
> >                                                                   ^ three?
> 
> Yes, perhaps I typed my accent here :)

Or because it's all about trees :)
 

-- 
Sincerely yours,
Mike.