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

["Joseph S. Myers" <joseph at codesourcery dot com>]

On Fri, 22 Nov 2013, Alexandre Oliva wrote:

> >> If keywords make sense on their own, readers won't look up their
> >> detailed definitions, and miss out on the details you regard as
> >> essential for them to be aware of.
> 
> > I'd like extended names, which are links to their definitions.
> 
> Do you acknowledge that this will not get users to follow the links so
> as to look at the precise definitions?

For conscientious readers, we need to include the link to make it easy for 
them to look up the documentation.  For unconscientious readers, there's 
only so much we can do.

>  -- Function: void setpwent (void)
>      | MT-Unsafe uses-a-static-buffer-overwritten-by-other-calls,

static-buffer (there's no need to make them complete phrases as long as 
the words are complete words or well-established abbreviations, but they 
shouldn't be glibc-specific abbreviations or run multiple words together 
with possible overlap).

(For functions where there are alternatives without global state, the 
important thing is to refer the reader to such alternatives.  But because 
getpwent_r still uses a global stream position, it's not a sufficient 
solution in this case.)

>      may-read-from-the-global-locale-object || AS-Unsafe

global-locale (or global-locale-read).

>      calls-the-dynamic-loader,
>      calls-functions-from-plugins-external-to-libc,
>      calls-memory-allocation-functions,
>      may-deadlock-with-itself-in-asynchronous-signal-handlers

Documenting limitations of safety only makes sense if we wish to support 
use of the function in a particular context provided the user follows 
particular rules.  In this case, and probably many cases for AS-Safety, I 
think we should just say AS-Unsafe - we don't want to support this in 
signal handlers at all, under any circumstances, and so don't need to 
document anything about what makes it unsafe, just that it is unsafe.

(But those could be dynamic-loader, plugins, malloc, deadlock - since it's 
in the AS-Unsafe section, mentioning "asynchronous-signal" as a context 
for deadlock is completely redundant.)

>      || AC-Unsafe
>      may-leave-data-structures-in-an-inconsistent-state-if-cancelled-asynchronously, 

data-structures-inconsistent (except I'd think that is a sufficiently 
fatal problem that the function should just be documented as 
unconditionally AC-Unsafe - the others are more like things a user could 
decide are acceptable in a particular case).

>      may-leave-locks-held-if-cancelled-asynchronously,

leak-locks

>      may-leak-file-descriptors-upon-asynchronous-cancellation,

leak-file-descriptors

>      may-leak-memory-upon-asynchronous-cancellation |

leak-memory

(Again, this is in the AC-Unsafe context, so don't need to mention 
asynchronous-cancellation in the keywords themselves.)

-- 
Joseph S. Myers
joseph@codesourcery.com