Linux-Fsdevel Archive on lore.kernel.org
help / color / mirror / Atom feed
From: "Darrick J. Wong" <firstname.lastname@example.org>
To: Alan Stern <email@example.com>
Cc: Dave Chinner <firstname.lastname@example.org>,
Eric Biggers <email@example.com>,
"Paul E . McKenney" <firstname.lastname@example.org>,
email@example.com, Akira Yokosawa <firstname.lastname@example.org>,
Andrea Parri <email@example.com>,
Boqun Feng <firstname.lastname@example.org>,
Daniel Lustig <email@example.com>,
David Howells <firstname.lastname@example.org>,
Jade Alglave <email@example.com>,
Luc Maranget <firstname.lastname@example.org>,
Nicholas Piggin <email@example.com>,
Peter Zijlstra <firstname.lastname@example.org>,
Will Deacon <email@example.com>
Subject: Re: [PATCH] tools/memory-model: document the "one-time init" pattern
Date: Mon, 20 Jul 2020 08:37:31 -0700 [thread overview]
Message-ID: <20200720153731.GB7597@magnolia> (raw)
On Mon, Jul 20, 2020 at 10:52:11AM -0400, Alan Stern wrote:
> On Mon, Jul 20, 2020 at 11:33:20AM +1000, Dave Chinner wrote:
> > On Sat, Jul 18, 2020 at 10:08:11AM -0400, Alan Stern wrote:
> > > > This is one of the reasons that the LKMM documetnation is so damn
> > > > difficult to read and understand: just understanding the vocabulary
> > > > it uses requires a huge learning curve, and it's not defined
> > > > anywhere. Understanding the syntax of examples requires a huge
> > > > learning curve, because it's not defined anywhere.
> > >
> > > Have you seen tools/memory-model/Documentation/explanation.txt?
> > <raises eyebrow>
> > Well, yes. Several times. I look at it almost daily, but that
> > doesn't mean it's approachable, easy to read or even -that I
> > understand what large parts of it say-. IOWs, that's one of the
> > problematic documents that I've been saying have a huge learning
> > curve.
> Can you be more specific? For example, exactly where does it start to
> become unapproachable or difficult to read?
> Don't forget that this document was meant to help mitigate the LKMM's
> learning curve. If it isn't successful, I want to improve it.
> > So, if I say "the LKMM documentation", I mean -all- of the
> > documentation, not just some tiny subset of it. I've read it all,
> > I've even installed herd7 so I can run the litmus tests to see if
> > that helps me understand the documentation better.
> > That only increased the WTF factor because the documentation of that
> > stuff is far, far more impenetrable than the LKMM documentation. If
> > the LKMM learnign curve is near vertical, then the stuff in the
> > herd7 tools is an -overhang-. And I most certainly can't climb
> > that....
> I can't argue with that. Really understanding herd7 does require a
> pretty extensive background in the field.
> > /me idly wonders if you recognise that your comment is, yet again, a
> > classic demonstration of the behaviour the "curse of knowledge"
> > cognitive bias describes.
> Not at all. I think you are confusing several different things.
> For one, at a purely literal level my comment could not possibly be
> taken as a demonstration of "curse of knowledge" behavior, because it
> was a simple question: Have you seen explanation.txt? Nothing obscure
> or outré about that.
> For another, you appear to be confusing the LKMM with the kernel's API,
> and reference documents with programming guides (or recipes). I'm sure
> that you aren't doing this deliberately and are well aware of these
> distinctions, but that's the impression your email leaves.
> > > That
> > > file was specifically written for non-experts to help them overcome the
> > > learning curve. It tries to define the vocabulary as terms are
> > > introduced and to avoid using obscure syntax.
> > It tries to teach people about what a memory model is at the same
> > time it tries to define the LKMM. What it doesn't do at all is
> > teach people how to write safe code.
> Of course it doesn't. It was never meant to. You can see this right in
> the filename "explanation.txt"; its purpose is to explain the LKMM.
> Nobody ever claimed it teaches how to write safe code or how to use the
> kernel's concurrent-programming API. Those things belong in a separate
> document, such as recipes.txt.
> > People want to write safe code,
> > not become "memory model experts".
> Speak for yourself. I personally want both, and no doubt there are
> others who feel the same way.
Ok then. I'm a lazy a***** maintainer who wants to write safe code
without first having to understand the memory models of *multiple CPU
architectures*, and I'm perfectly fine with accepting the smallest
common featureset across those CPUs so that I can think as little as
possible about things outside my area of expertise.
Willy's proposed API looks good enough for me, and if that's all I ever
have to know, I'm good with that. Eric's proposed recipes patch is a
decent breadcrumb should I ever desire to know more. I don't expect
I'll read the LKMM, just like I don't expect any of the rest of you will
read the XFS internals book.
(Well, ok, I imagine Dave has...)
> > Memory models are -your expertise- but they aren't mine. My
> > expertise is filesystems: I don't care about the nitty gritty
> > details of memory models, I just want to be able to write lockless
> > algorithms correctly. Which, I might point out, I've been doing for
> > well over a decade...
> That's perfectly fine; I understand completely. But your criticism is
> misplaced: It should be applied to recipes.txt, not to explanation.txt.
> And remember: It was _you_ who claimed: "just understanding the
> vocabulary [the LKMM] uses requires a huge learning curve, and it's not
> defined anywhere". explanation.txt shows that this statement is at
> least partly wrong. Besides, given that you don't care about the nitty
> gritty details of memory models in any case, why are you complaining
> that understanding the LKMM is so hard?
> My impression is that you really want to complain about the inadequate
> quality of recipes.txt as a programmers' guide. Fine, but don't extend
> that to a blanket condemnation of all the LKMM documentation.
> > > If you think it needs improvement and can give some specific
> > > details about where it falls short, I would like to hear them.
> > Haven't you understood anything I've been saying? That developers
> > don't care about how the theory behind the memory model or how it
> > works - we just want to be able to write safe code.
> Again, speak for yourself.
> > And to do that
> > quickly and efficiently. The "make the documentation more complex"
> > response is the wrong direction. Please *dumb it down* to the most
> > basic, simplest, common concurrency patterns that programmers use
> > and then write APIs to do those things that *hide the memory model
> > for the programmer*.
> > Adding documentation about all the possible things you could do,
> > all the optimisations you could make, all the intricate, subtle
> > variations you can use, etc is not helpful. It might be interesting
> > to you, but I just want -somethign that works- and not have to
> > understand the LKMM to get stuff done.
> In principle, both can be included in the same document. Say, with the
> more in-depth discussions relegated to specially marked-off sections
> that readers are invited to skip if they aren't interested.
> > Example: I know how smp_load_acquire() works. I know that I can
> > expect the same behavioural semantics from smp_cond_load_acquire().
> > But I don't care how the implementation of smp_cond_load_acquire()
> > is optimised to minimise ordering barriers as it spins. That sort of
> > optimisation is your job, not mine - I just want a function that
> > will spin safely until a specific value is seen and then return with
> > acquire semantics on the successful load.....
> > Can you see the difference between "understanding the LKMM
> > documenation" vs "using a well defined API that provides commonly
> > used functionality" to write correct, optimal code that needs to
> > spin waiting for some other context to update a variable?
> Certainly I can. Can't _you_ see the difference between a document that
> helps people "understand the LKMM" and one that demonstrates "using a
> well defined API that provides commonly used functionality"?
> > That's the problem the LKMM documentation fails to address. It is
> > written to explain the theory behind the LKMM rather than provide
> > developers with pointers to the templates and APIs that implement
> > the lockless co-ordination functionality they want to use....
> That's the difference between a reference document and a programmers'
> guide. Grousing that one isn't the other is futile.
> On the other hand, pointing out specific areas of improvement for a
> document that was meant to be a programmers' guide can be very helpful.
> You may not be inclined to spend any time editing recipes.txt, but
> perhaps you could point out a few of the specific areas most in need of
> Alan Stern
next prev parent reply other threads:[~2020-07-20 16:46 UTC|newest]
Thread overview: 39+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-07-17 4:44 Eric Biggers
2020-07-17 5:49 ` Sedat Dilek
2020-07-17 12:35 ` Matthew Wilcox
2020-07-17 14:26 ` Alan Stern
2020-07-17 17:47 ` Matthew Wilcox
2020-07-17 17:51 ` Alan Stern
2020-07-18 1:02 ` Eric Biggers
2020-07-27 12:51 ` Matthew Wilcox
2020-07-17 21:05 ` Darrick J. Wong
2020-07-18 0:44 ` Darrick J. Wong
2020-07-18 1:38 ` Eric Biggers
2020-07-18 2:13 ` Matthew Wilcox
2020-07-18 5:28 ` Eric Biggers
2020-07-18 14:35 ` Alan Stern
2020-07-20 2:07 ` Dave Chinner
2020-07-20 9:00 ` Peter Zijlstra
2020-07-27 15:17 ` Alan Stern
2020-07-27 15:28 ` Matthew Wilcox
2020-07-27 16:01 ` Paul E. McKenney
2020-07-27 16:31 ` Alan Stern
2020-07-27 16:59 ` Matthew Wilcox
2020-07-27 19:13 ` Alan Stern
2020-07-17 20:53 ` Darrick J. Wong
2020-07-18 0:58 ` Eric Biggers
2020-07-18 1:25 ` Alan Stern
2020-07-18 1:40 ` Matthew Wilcox
2020-07-18 2:00 ` Dave Chinner
2020-07-18 14:21 ` Alan Stern
2020-07-18 2:00 ` Eric Biggers
2020-07-18 1:42 ` Dave Chinner
2020-07-18 14:08 ` Alan Stern
2020-07-20 1:33 ` Dave Chinner
2020-07-20 14:52 ` Alan Stern
2020-07-20 15:37 ` Darrick J. Wong [this message]
2020-07-20 15:39 ` Matthew Wilcox
2020-07-20 16:04 ` Paul E. McKenney
2020-07-20 16:48 ` peterz
2020-07-20 22:06 ` Paul E. McKenney
2020-07-20 16:12 ` Alan Stern
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--subject='Re: [PATCH] tools/memory-model: document the "one-time init" pattern' \
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
This is a public inbox, see mirroring instructions
on how to clone and mirror all data and code used for this inbox