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

[Torvald Riegel <triegel at redhat dot com>]

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").