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 09:57 PM, Alexandre Oliva wrote:
> On Jan 31, 2014, "Carlos O'Donell" <carlos@redhat.com> wrote:
> 
>> OK to checkin if the answer to the question below is "Yes."
>  
>>> +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.
> 
> Well, I can't answer âYesâ to that.
> 
> Under âsigâ, for example, we document that the identifier specifies the
> signal that is unsafely used.

Sorry, yes that's right.
 
> The cases of brk(filedes) and tcattr(filedes) name actual properties
> that may conflict with other functions that set properties of a
> terminal, as mentioned under âtermâ.

Why not just use term then?

The problem I have is that this violates what it says in "race"
specifically:
~~~
We will annotate, with @code{race} followed by a colon and the
argument name, functions that take such objects but that do not take
care of synchronizing access to them by default.
~~~

In tcflow for example we have "race:tcattr(filedes)/bsd".

The string after the colon is not an argument name.

I'd expect "race:filedes/bsd term/bsd" perhaps.

> In a number of cases, we don't even group *several* functions; a single
> function may be named, when it's the only function using some static
> buffer.
> 
> Nevertheless...

So the problem is that this is a complicated safety note. I'd rather
you removed them and added a "Safety Note:" with detailed text to the
actual function explaining the quirks. That way the the properties are
well documented.

>> In which case `buf(arg)' is technically an opaque identifier that groups
>> other `buf(arg)'s together right?
> 
> I guess I could say âyesâ to this, with the caveats above.  In *most*
> cases it's ok to just use it as an opaque grouping identifier, in spite
> of the attempts to make it mnemonic as well.  But there's the
> brk/tcattr/term exception; IIRC that's the only one in which treating
> the identifiers are purely opaque would enable safe workarounds for
> safety problems.  E.g., on BSD, someone who wanted to call âtermâ-marked
> functions would have to guard tcattr- and brk-marked functions operating
> on the same file descriptor.
> 
> So, is this good enough?  Or should brk(filedes) be marked with
> tcattr(filedes) as well, to ensure proper guarding based on strict
> matching of identifiers?

In summary:

- What do you think if using [] for signals instead of : to avoid the
  overlap with identifiers? e.g. sig[SIGFOO].

- What do you think of removing brk(filedes) and tcattr(filedes) and
  instead adding a "Safety note:" to the function and describing in
  more detail what's actually tricky about it?

  or

  Rewrite the safety notes using the marker semantics we documented.

Cheers,
Carlos.