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

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

On 02/01/2014 12:13 AM, Alexandre Oliva wrote:
> After some IRC conversation, we converged on dropping brk(filedes) in
> favor of tcattr(filedes), with an update to the definition of term to
> make this conflict clearer.
> 
> 
> Here's the resulting intro.texi patch.  I'll post the updated
> terminal.texi patch in its own subthread.
> 
> 
> 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.

OK to checkin with typos fixed and some note about why identifiers
are important is added.

> ---
>  manual/intro.texi |   43 ++++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 40 insertions(+), 3 deletions(-)
> 
> diff --git a/manual/intro.texi b/manual/intro.texi
> index fb501a6..fcbdacf 100644
> --- a/manual/intro.texi
> +++ b/manual/intro.texi
> @@ -669,7 +669,10 @@ concurrent and reentrant interactions with it, by not using it in signal
>  handlers or blocking signals that might use it, and holding a lock while
>  calling these functions and interacting with the terminal.  This lock
>  should also be used for mutual exclusion with functions marked with
> -@code{@mtasurace{:tcattr}}.
> +@code{@mtasurace{:tcattr(fd)}}, where @var{fd} is a file descriptor for
> +the controlling terminal.  The caller may use a single mutex for
> +simplicity, or use one mutexes per terminal, even if referenced by

s/mutexes/mutex/g

> +different file descriptors.
>  
>  Functions marked with @code{term} as an AC-Safety issue are supposed to
>  restore terminal settings to their original state, after temporarily
> @@ -698,7 +701,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 +731,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 +856,42 @@ properties we documented are identical to those mandated by POSIX for
>  the corresponding functions.
>  
>  
> +@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{:tcattr(fd)} to denote the terminal attributes of a
> +file descriptor @var{fd}.

Suggest adding:

The most common use for identifiers is to provide logical groups
of functions and arguments that need to be protected by the same
synchronization primitive in order to ensure safe operation in
a given context.

> +
> +
> +@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.
> +
> +
>  @end itemize
>  
>  
> 
> 

Cheers,
Carlos.