This is the mail archive of the mailing list for the glibc project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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

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.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]