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

From: Mike Rapoport
Date: Thu Feb 03 2022 - 03:57:57 EST


On Thu, Feb 03, 2022 at 02:38:42AM +0000, Liam Howlett wrote:
> * Mike Rapoport <rppt@xxxxxxxxxx> [220202 12:11]:
> > Hi Liam,
> >
> > On Wed, Feb 02, 2022 at 02:41:56AM +0000, Liam Howlett wrote:
> > > From: "Liam R. Howlett" <Liam.Howlett@xxxxxxxxxx>
> > >
> > > +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@xxxxxxxxxx>
> > > + * Matthew Wilcox <willy@xxxxxxxxxxxxx>
> > > + */
> > > +
> > > +#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.