Re: [MTASCsft PATCH 09/??] MT-, AS- and AC-Safety docs: manual/errno.texi

["Carlos O'Donell" <carlos at redhat dot com>]

On 01/31/2014 08:08 PM, Alexandre Oliva wrote:
> On Jan 31, 2014, "Carlos O'Donell" <carlos@redhat.com> wrote:
> 
>> We should not add things that we have not described in the introduction.
> 
> How about this?
> 
> (I've also dropped comments about the need to revisit some markers that
>  I've already revisied; they shouldn't have made it in the first place)

OK to checkin if the answer to the question below is "Yes."
 
> 
> MT-, AS- and AC-safety docs: identifiers and conditionals
> 
> From: Alexandre Oliva <aoliva@redhat.com>
> 
> for ChangeLog
> 
> 	* manual/intro.texi: Document safety identifiers and
> 	conditionals.
> ---
>  manual/intro.texi |   38 ++++++++++++++++++++++++++++++++++++--
>  1 file changed, 36 insertions(+), 2 deletions(-)
> 
> diff --git a/manual/intro.texi b/manual/intro.texi
> index fb501a6..3387dc1 100644
> --- a/manual/intro.texi
> +++ b/manual/intro.texi
> @@ -698,7 +698,6 @@ taken into account in certain classes of programs:
>  
>  @itemize @bullet
>  
> -@c revisit: uses are mt-safe, distinguish from const:locale
>  @item @code{locale}
>  @cindex locale
>  
> @@ -729,7 +728,6 @@ constant in these contexts, which makes the former safe.
>  @c because of the unexpected locale changes.
>  
>  
> -@c revisit: this was incorrectly used as an mt-unsafe marker.
>  @item @code{env}
>  @cindex env
>  
> @@ -855,6 +853,42 @@ properties we documented are identical to those mandated by POSIX for
>  the corresponding functions.
>  

OK, added after the last safety remark in "Other Safety Remarks"

> +@item @code{:identifier}
> +@cindex :identifier
> +
> +Annotations may sometimes be followed by identifiers, intended to group
> +several functions that e.g. access the data structures in an unsafe way,
> +as in @code{race} and @code{const}, or to provide more specific
> +information, such as naming a signal in a function marked with
> +@code{sig}.  It is envisioned that it may be applied to @code{lock} and
> +@code{corrupt} as well in the future.
> +
> +In most cases, the identifier will name a set of functions, but it may
> +name global objects or function arguments, or identifiable properties or
> +logical components associated with them, with a notation such as
> +e.g. @code{:buf(arg)} to denote a buffer associated with the argument
> +@var{arg}, or @code{:brk(fd)} to denote the @code{brk} terminal property
> +of a file descriptor @var{fd}.

OK, as long as the idenfifier's only purpose is to group several functions.

In which case `buf(arg)' is technically an opaque identifier that groups
other `buf(arg)'s together right?

> +
> +
> +@item @code{/condition}
> +@cindex /condition
> +
> +Some safety annotations may be conditional, in that they only apply if a
> +boolean expression involving arguments, global variables or even the
> +underlying kernel evaluates evaluates to true.  Such conditions as
> +@code{/hurd} or @code{/!linux!bsd} indicate the preceding marker only
> +applies when the underlying kernel is the HURD, or when it is neither
> +Linux nor a BSD kernel, respectively.  @code{/!ps} and
> +@code{/one_per_line} indicate the preceding marker only applies when
> +argument @var{ps} is NULL, or global variable @var{one_per_line} is
> +nonzero.  
> +
> +When all marks that render a function unsafe are adorned with such
> +conditions, and none of the named conditions hold, then the function can
> +be regarded as safe.
> +
> +

OK.

>  @end itemize
>  
>  
> 
> 

Cheers,
Carlos.