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. 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.... /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. > 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. People want to write safe code, not become "memory model experts". 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... > 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. 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. 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? 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.... Cheers, Dave. -- Dave Chinner david@xxxxxxxxxxxxx
