This is the mail archive of the libc-alpha@sourceware.org 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 Sat, 23 Nov 2013, Alexandre Oliva wrote:

> Torvald values the annotations that justify (for internal consumers, not
> in the formatted manual) why a function is AS-Unsafe or AC-Unsafe, as I
> do.  Using macros for them that expand to nothing is fine, but what
> about the documentation that currently defines them?  Should it be
> removed altogether, or turned into comments?

I have no advice about that.

> > 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 point is to document why it is unsafe.

The point of the documentation should be to make clear to users under what 
circumstances (with the current implementation, or, better, under what 
circumstances as an explicit choice about the API we wish to support) a 
function may safely be used.  If the answer is that the function should 
never be used in AS or AC circumstances, then we don't need to say why in 
the formatted manual, just that the answer is never.

> > (Again, this is in the AC-Unsafe context, so don't need to mention 
> > asynchronous-cancellation in the keywords themselves.)
> 
> The *definitions* of the keywords are not divided in sections, because
> some keywords apply to more than one section.  Since there's a single
> namespace for the definitions, in cases in which the distinction is
> significant, it becomes necessary to have different keywords, and then
> I've resorted to bringing the context into the keyword name.

I think in these cases the definition of the keyword should describe what 
it means in each context.

> Furthermore, if we're to link to the section that defines the macros,
> the @safety macro would need some way to tell that at least one of the
> keyword macros mentioned in arguments to its arguments expanded to a
> non-empty string in order to determine whether to expand the xref.  I'm
> not sure this is possible in texinfo, and it doesn't make sense to add
> the xrefs manually if the macros themselves may come and go.

Definitions should always be linked to, simply to define the MT-Safe etc. 
terms even if no keywords for more specific safety information are 
present.

-- 
Joseph S. Myers
joseph@codesourcery.com


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