Re: Consensus on MT-, AS- and AC-Safety docs.

[Torvald Riegel <triegel at redhat dot com>]

On Tue, 2013-11-19 at 12:21 +0100, Torvald Riegel wrote:
> On Mon, 2013-11-18 at 15:46 -0500, Carlos O'Donell wrote:
> > Joseph, Torvald, Rich,
> > 
> > The three of you have made long or brief comments on the work
> > that Alex has posted on the mailing list titled:
> > "MT-, AS- and AC-Safety docs."
> > 
> > The work itself is a detailed code review with the goal to
> > document multi-threaded safety, asynchronous-signal safety,
> > and asynchronous-cancellation safety in the glibc manual (the
> > canonical place for such documentation).
> > 
> > The documentation adds the safety information along with
> > exception information. The exceptions are broken down into
> > groups and reflect the implementation realities and limitations
> > of glibc.
> > 
> > We have already set aside the discussion that the multi-threaded
> > guarantees we provide are insufficient to help users answer all
> > of the questions they might have about their program's behaviour.
> > That discussion has changed scope and the goal there is going to
> > be to have the upstream POSIX language changed. Torvald, that's
> > something that you, and I and other interested parties can do.
> > 
> > The desire to fix bugs as we find them is strong. We are all
> > interested in the well being of the project, but to stop the
> > documentation effort in mid-swing is to loose momentum. Therefore
> > Alex has been filing bugs as he finds them instead of fixing them.
> > Some bugs run deep and some functions will need to be rewritten to
> > be MT-safe, and that's a lot of work. Remember the goal here is
> > documentation. Once the documentation is done we can do a bug
> > fixing pass with the knowledge of everything in the library that
> > is potentially broken.
> > 
> > Having said all this, do any of you object in any way to the
> > addition of this documentation?
> 
> I have commented on the definitions (patch 00/33) and would prefer a few
> changes/clarifications there, but nothing major.  Thus, no objection
> from me -- I think this is a good start.  We now have some guidance to
> which particular properties we might need to specify properly (ie, not
> just "thread safety" but also the individual exceptions that would arise
> in practice for an implementation such as glibc's).  We might have to
> make another pass over the docs once we have proper definitions, but
> it's definitely better to have some docs than no docs.  Nonetheless, I
> also agree with Joseph that we should make the caveats clearly visible
> (eg, that this documents current state without formal definitions, and
> is not a promise to guarantee any interpretation of "thread safety").

After the recent discussions with Alex, I'm not so sure anymore that
it's clear what's actually being documented; the MT-Safety definition
just isn't sufficiently detailed enough in my opinion to be actually
helpful on its own (nor is POSIX definition).  Things like not getting a
to me sufficient definition even after lengthy email threads with Alex,
and points like the discussion around nonatomic single-word loads in
MT-Safe functions don't give me a lot of confidence that we're putting
something out there that won't be misunderstood.  That Alex chose to
stop participating in that aspect of the discussion isn't giving me a
lot of confidence either.

I still think that having some imperfect docs is better than no docs,
but IMO we need to do something about the MT-Safe definition itself.  I
see these options:

1) Keep it as-is, cross fingers.

2) Keep it as-is, add a disclaimer that, essentially, we haven't yet
fully agreed on what this actually all means.

3) Add a sufficiently precise but conservative MT-Safe definition. "Your
program will not crash during the execution of MT-Safe functions,
provided the state visible to the thread executing the function fits the
precondition of the function as specified." would be one possibility
(with some more detail added).  That might not be very helpful to
programmers, but it would be much more likely to be correct.  Iterate on
getting it less conservative after 2.19.

4) Like 3), but try to get as close to the definition that Alex had in
mind when documenting, before 2.19.

I don't like 1), for obvious reasons (from my POV).  2) would be okay to
me given the 2.19 schedule.  3) is doable too, I believe, and might be
better than 2) because we could use the feedback we hopefully get for a
definition that is correct but not quite useful to improve it in the
future.  4) should also be possible (and I could help with this), but
this needs Alex' involvement (I can't read his mind) -- and his
agreement that we actually need a more detailed definition.

Regarding the keywords, I've burnt enough discussion cycles to care much
anymore.  If those are really macros and we can thus change rather
easily how we present this, we can apply changes later.

That's my opinion on it, and my vote.  I'll leave it to the rest of the
community to decide how to proceed.