Thread-, Signal- and Cancellation-safety documentation

[Alexandre Oliva]

On Mar 26, I wrote:

> I've (not so) recently started working on documenting these safety
> properties of glibc functions.  I believe now have enough of a
> patchset to get the discussion on form and content started.

First of all, I'd like to thank everyone who provided feedback.  I'm
embarrassed to admit that, although so many weeks have elapsed, I
probably still have some issues to double-check from the feedback I got,
and fix them if appropriate.  The reason for so much delay was that,
after we decided that the possibility of setlocale races should not
cause printf to be MT/AS-Unsafe, I started going through the complete
graph of dependencies of the printf family for a complete assessment,
and that was too much to fit in the working set of my puny brain ;-) I
started thrashing, getting frustrated, and decided to leave that alone
for a while and get on to other parts of the library to rebuild my
self-confidence.

But then, I talked to Carlos and we decided to prioritize getting the
work that was already done into a form that could hopefully become part
of the manual in the trunk, signaling to a broader community that
there's work underway in this front, making the useful information
collected so far available to a broader audience, and consolidating the
growing consensus on the form this documentation should take.

I believe two major points of consensus arose that diverged from my
original plan, and the upcoming patchset implements them both: (i)
documenting that the currently documented safety properties are not a
promise (yet), but an assessment of the current status to determine what
needs fixing and what promises we can make, and (ii) binary Safe/Unsafe
is highly overrated, and we should provide a lot more user-visible
detail about what makes some functions unsafe and under which
constraints they may actually be safe.

The main point of this updated patchset, already uploaded to branch
lxoliva/thread-safety-docs, was to implement these two decisions,
consolidating and documenting in the manual all of the issues I'd
already noticed.  The branch actually contains a few more patches on top
of those below, with notes meant mainly for myself (for now) and
documentation of a few printf dependencies here and there in files I
haven't fully covered yet; these other patches not posted below aren't
anywhere even close to being ready for the trunk, but interested parties
might want to peek at the branch to see what else is there.


You might notice I've changed the spelling of some of the notes, and
also grouped and split some, in the process of documenting the different
properties and recommendations.  In all cases, I chose single made-up
words (rather than English words) because I intend to eventually turn
the keywords into macros that would provide active linking to the
definitions; made-up words will make it easier to do so as a single
global-replace-string.

One point I'm unsure about is whether to keep the keywords “under”
specific safety criteria (MT, AS or AC), or promote them to stand-alone
notes *sibling* to (MT|AS|AC)-(Safe|Unsafe).  In my latest pass over the
patchset, I aimed at getting each keyword associated with a single
safety criterion (though now I'm not quite sure I succeeded), so that
the promotion would be possible, but I'd like opinions on which of these
look better, or suggestions of other better ways to present this
kind of information:

Current:
| MT-Unsafe uunguard || AS-Unsafe asynconsist || AC-Safe fdleak, memleak |

Alternative 1:
| MT-Unsafe || uunguard || AS-Unsafe || asynconsist || AC-Safe || fdleak || memleak |

Alternative 2:
| MT-Unsafe || AS-Unsafe || AC-Safe || uunguard || asynconsist || fdleak || memleak |

Alternative 3:
| MT-Unsafe || AS-Unsafe || AC-Safe |
[ uunguard ][ asynconsist ][ fdleak ][ memleak ]

Alternative 4:
| MT-Unsafe || AS-Unsafe || AC-Safe |
@xref{uunguard}
@xref{asynconsist}
@xref{fdleak}
@xref{memleak}

Alternative N:
??


Thanks,


-------------- next part --------------
A non-text attachment was scrubbed...
Name: manual-document-mt-safety.patch
Type: text/x-diff
Size: 14271 bytes
Desc: not available
URL: <http://sourceware.org/pipermail/libc-alpha/attachments/20130503/7361bf7f/attachment.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: manual-document-mt-safety-arith.patch
Type: text/x-diff
Size: 40221 bytes
Desc: not available
URL: <http://sourceware.org/pipermail/libc-alpha/attachments/20130503/7361bf7f/attachment-0001.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: manual-document-mt-safety-stdio.patch
Type: text/x-diff
Size: 59180 bytes
Desc: not available
URL: <http://sourceware.org/pipermail/libc-alpha/attachments/20130503/7361bf7f/attachment-0002.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: manual-document-mt-safety-locale.patch
Type: text/x-diff
Size: 963 bytes
Desc: not available
URL: <http://sourceware.org/pipermail/libc-alpha/attachments/20130503/7361bf7f/attachment-0003.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: manual-document-mt-safety-math.patch
Type: text/x-diff
Size: 681 bytes
Desc: not available
URL: <http://sourceware.org/pipermail/libc-alpha/attachments/20130503/7361bf7f/attachment-0004.bin>
-------------- next part --------------


-- 
Alexandre Oliva, freedom fighter    http://FSFLA.org/~lxoliva/
You must be the change you wish to see in the world. -- Gandhi
Be Free! -- http://FSFLA.org/   FSF Latin America board member
Free Software Evangelist      Red Hat Brazil Compiler Engineer