Re: Thread-, Signal- and Cancellation-safety documentation

[Roland McGrath <roland at hack dot frob dot com>]

I am not reviewing any of this in detail, as others seem to be pretty well
on top of that.

The manual does not document what the current behavior happens to be.  It
documents the interface contract.  So examining the implementation is a
good starting point for the two things that need to be done: documenting
(and, in some cases, deciding) what the contract is; and filing (and then
fixing) a bug for each case where the implementation does not meet its
contract.  But examining the implementation per se is most certainly not
the way to determine what we should say in the manual.

Cases like stdio vs fsetlocking are a subtlety that needs to be explained
clearly and represented by more specific categories.  I don't think it's
the right approach to pick the broad categories a priori and then put each
square peg into the largest round hole it fits.  We need more categories,
e.g. "stdio-MT-safe" for what's the case of stdio functions given the
possibility of fsetlocking, and then to document each such specialized
category clearly.


Thanks,
Roland