Re: [MTASCsft PATCH WIP5 01/33] Multi Thread, Async Signal and Async Cancel safety documentation: intro

[Alexandre Oliva <aoliva at redhat dot com>]

On Nov 18, 2013, "Carlos O'Donell" <carlos@redhat.com> wrote:

> On 11/13/2013 03:11 AM, Alexandre Oliva wrote:
>> +The safety properties of @glibcadj{} functions, documented as MT-, AS-
>> +and AC- -Safe and -Unsafe are assessed according to the criteria set
>> +forth in the POSIX standard for Multi-Thread, Async-Signal and

> Should this be "Multi-Threaded" ?

I don't think so.  Although POSIX uses multi-threaded as a qualifier for
programs, applications, processes, and environments, with only one
exception in section B that spells âmulti-thread applicationâ, there is
no occurrence whatsoever of Threaded-Safety, it's always Thread-Safety,
and it's safety that Multi-Thread, Async-Signal and Async-Cancel qualify
above.

The question then is whether to drop âMulti-â.  Since MT-Safe is widely
used as a term to denote Thread-Safety, I'd keep it:

  forth in the POSIX standard for Thread-, Async-Signal- and
  Async-Cancel- safety.

The definition of MT-Safe then expands MT into Multi Thread.


>> +Async-Cancel safety.

> Please spell out "Async" as "Asynchronous" for this first use (you'll
> be using the short forms from now on).

Since we're [rd]eferring to the definitions in the POSIX standard, we
should use the terms as they're defined there.  That's why I added the
dashes and dropped the Multi- in the proposed change above.

>> +@end itemize
>> +
>> +By ``safe to call'', we mean that, as long as the program does not
>> +invoke undefined or unspecified behavior, the called functions will
>> +behave as documented, and they won't cause any other functions to

> Suggest we avoid contractions in such a formal document
> e.g. and they will not cause...

There are other contractions in the manual, but ok, I've expanded those
I introduced in intro.texi, except those I introduced within comments.

>> +@c glocale-revisit

> ^^^^^^^^^^^^^^^^^^^^^^ What does this mean?

It meant I had to revisit functions marked with glocale after our
long-ago decision of regarding uselocale/setlocale as unsafe, instead of
regarding locale-users as such.

Come to think of it, I'm not entirely sure I kept this in mind when
marking functions with glocale when they used the locale in ways that
would be unsafe in case of locale changes; I'll probably have to
double-check this, as well as envromt, in which a similar distinction
was made but AFAICT I lost track of it.

>> +Environment-modifying functions do not protect in any way against
>> +concurrent modifications or access, so calling @code{envromt}-marked

> s/access, so calling/access.  Calling/g

I liked the cause/consequence relationship of the two sentences implied
by the âsoâ, but I won't fight for it; dropped.

>> +@item @code{1stcall}

> This last statement is a bit confusing to me.

I've replaced the two paragraphs that are mostly redundant with this:

  Calling such a function at least once in single-threaded mode removes
  this specific cause for the function to be regarded as MT-Unsafe.  If
  no other cause for that remains, the function can then be safely
  called after other threads are started.


> Suggest "while holding internal dynamic loader locks."

> Suggest  "The locks are enough for these functions to be AS- and AC-Unsafe."

Taken.

> What other issues may arise? Can we narrow the scope?

That's TBD, as I haven't reviewed the dynamic loader yet.

>> +While the problem is similar to that of file descriptors, in that there
>> +is not any atomic interface to lock and take note of the need for
>> +unlocking in a cleanup, or to unlock and take note that there is no
>> +longer such a need, the problem posed by lock leaks is far more serious:
>> +when a file descriptor or a piece of memory is leaked, it becomes
>> +inaccessible and subsequent attempts to allocate a file descriptor or
>> +some memory will just use another resource.  However, once a lock is
>> +left taken, attempts to take that lock will block indefinitely.

> Agreed. Though I wouldn't say it's more serious than other problems since
> all it does is deadlock threads calling these functions.

Which is far less serious than the other *leak notes, as detailed above.
If it wasn't, there wouldn't be justification to regard lockleak as
AC-Unsafe, while memleak and fdleak are still AC-Safe.

>> +If such a function is asynchronously canceled, it may leave the data

> s/canceled/cancelled/g

AFAICT both forms are correct, but I'd used both, which seems odd, so,
taken.

>> +only safe way to avoid the misbehavior that may ensure if the thread is

> Suggest: s/that may ensure//g

Fixed s/ensure/ensue/ first ;-)

>> +This note does not cause functions to be marked as MT-Unsafe, even
>> +though, on the affected platform, they are MT-Unsafe indeed.

> s/ indeed//g.

simfpu was dropped altogether.

>> +@item @code{unposix}
>> +@cindex unposix

> So this acts as a warning to call out areas we've noticed, but it isn't
> 100% complete?

Yeah, but it's more like 0% complete; I have avoided looking at the
requirements in the standard to avoid (mis)guiding myself in the
assessment of the functions.  IIRC there was only one case in which the
difference was pointed out to me, so I took note of it.

> If all goes well I think we can go checking things in one patch at a time.

Sounds good to me.  I'll go through Torvald's email, then try to find a
way to accommodate Joseph's concerns about misleading users, and finally
post a revised patch.

-- 
Alexandre Oliva, freedom fighter    http://FSFLA.org/~lxoliva/
You must be the change you wish to see in the world. -- Gandhi
Be Free! -- http://FSFLA.org/   FSF Latin America board member
Free Software Evangelist      Red Hat Brazil Compiler Engineer