This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: Consensus on MT-, AS- and AC-Safety docs.
- From: Torvald Riegel <triegel at redhat dot com>
- To: "Joseph S. Myers" <joseph at codesourcery dot com>
- Cc: Alexandre Oliva <aoliva at redhat dot com>, "Carlos O'Donell" <carlos at redhat dot com>, GNU C Library <libc-alpha at sourceware dot org>, Rich Felker <dalias at aerifal dot cx>
- Date: Fri, 22 Nov 2013 23:23:01 +0100
- Subject: Re: Consensus on MT-, AS- and AC-Safety docs.
- Authentication-results: sourceware.org; auth=none
- References: <528A7C8F dot 8060805 at redhat dot com> <Pine dot LNX dot 4 dot 64 dot 1311182312130 dot 8831 at digraph dot polyomino dot org dot uk> <orob5fv8nl dot fsf at livre dot home> <Pine dot LNX dot 4 dot 64 dot 1311201555320 dot 28804 at digraph dot polyomino dot org dot uk> <orli0itbm5 dot fsf at livre dot home> <Pine dot LNX dot 4 dot 64 dot 1311211322040 dot 14539 at digraph dot polyomino dot org dot uk> <or4n75t4b7 dot fsf at livre dot home> <Pine dot LNX dot 4 dot 64 dot 1311221324200 dot 5029 at digraph dot polyomino dot org dot uk> <orob5csdvx dot fsf at livre dot home> <Pine dot LNX dot 4 dot 64 dot 1311221535560 dot 8443 at digraph dot polyomino dot org dot uk>
On Fri, 2013-11-22 at 15:46 +0000, Joseph S. Myers wrote:
> 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.
I agree that it makes it easier, but personally I don't think it's
really critical.
> > -- 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).
I agree. If we use words that people know, then it is just easier to
remember. For example, if I see "envromt", I'd probably remember it as
"the thing that looks like environment"; thus, the abbreviation would be
just another indirection people have to remember (or, it would require
another indirection(/hint) to actually remember it).
> (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.
I'd prefer if we'd put macros with this information into the
documentation, even if we should choose to let them expand to empty
strings. Right now, I don't see much of a benefit of maintaining the
reasons somewhere external.
> (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.)
>
Those suggestions all look fine to me. They point in a right direction,
without looking like full descriptions; and they are easy to read,
remember, speak out, etc.
- References:
- Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.
- Re: Consensus on MT-, AS- and AC-Safety docs.