[MTASCsft PATCH WIP4 00/28] MT-, AS- and AC-Safety docs

[Alexandre Oliva <aoliva at redhat dot com>]

Here's an updated version of the patch series that documents
Multi-Thread, Async Signal and Async Cancel safety properties of our
implementation.

A number of large files were completed since the last round.  I've
added the new marks oncesafe and 1stcall, both having to do with
certain internal initialization scenarios that might bring about
safety issues.

I haven't yet sorted out the uunguard/xguargs (/staticbuf?) mess that
Florian Weimer pointed out; the definitions are at times overlapping
and insufficient for some cases I've run into, so there's work to do
there.  I think we need to document and perhaps distinguish situations
in which a function uses (and/or modifies) in unsafe says:

- libc-owned data, perhaps distinguishing cases in which:

-- the data is accessible to the user (global variables, return
values, whatever), that should be marked with staticbuf; or

-- the data is completely internal to libc (say some internal
initialized_p variable), that could be marked with staticbuf as well,
although that might deviate from the way the term is normally used,
but uunguard would be more appropriate in some cases, because it
implies that the data is safe to read, because all modifiers are
marked as unsafe to call;

- user-manipulable data, but it's not clear that we should distinguish
those in which:

-- the data is opaque to users (streams, obstacks, locks?, etc), so
there may be a reasonable expectation that libc will access/modify it
safely, because nothing else could (it doesn't hold for obstacks, for
example, so those would be marked with xguargs, that implies the need
for external synchronization, not uunguard, because there's no implied
safety to read);

-- the data is exposed to users (strings, time* and stat* structs,
etc), whose internals can be inspected and modified at will, so that,
in the absence of an explicit protocol to access them safely (e.g.,
streams with automatic locking disabled), the user must arrange for
exclusive access to avoid races; uunguard and xguargs may cover this,
depending on the safety guarantees for readers, as noted above;
however, for user-exposed data, I'm thinking *no* safety note is
required: the documented behavior of the function indicates what kind
of synchronization the user ought to use; failing that, we'd have to
mark all string and formatting functions with a note that flags the
need for exclusive access when the function may modify such exposed
data, and/or for the data to not be modified elsewhere when the
function only reads from it.  We could do that, but it feels excessive
and somewhat misguided.

Thoughts?


Here's a summary of of the number of @deftypefu?n entries in each file
in the manual, how many @safety notes there are, how complete the
safety documentation for that file is, and how many other functions
I've (so far) noticed as not documented at all in the manual, but that
should be documented in that file (with a @safety note to go with it)

            Filename @def @saf  cmplt% undoc
   manual/stdio.texi  126  126 100.00%   0                                      
   manual/arith.texi  102  102 100.00%   0
  manual/string.texi   99   99 100.00%   1
    manual/math.texi   86   86 100.00%   0
 manual/filesys.texi   78   78 100.00%  18
    manual/llio.texi   53   53 100.00%   1
   manual/ctype.texi   36   36 100.00%   0
 manual/charset.texi   18   18 100.00%   0
   manual/errno.texi   13   13 100.00%   0
     manual/job.texi   11   11 100.00%   0
   manual/crypt.texi   10   10 100.00%   0
    manual/lang.texi    7    7 100.00%   0
    manual/argp.texi    6    6 100.00%   0
  manual/locale.texi    5    5 100.00%   0
    manual/conf.texi    4    4 100.00%   0
   manual/debug.texi    3    3 100.00%   0
  manual/getopt.texi    3    3 100.00%   0
----
----
 manual/process.texi   22   20  90.91%   0
  manual/search.texi   15    7  46.67%   0
  manual/memory.texi   44   14  31.82%   0
 manual/pattern.texi   11    3  27.27%   0
manual/resource.texi   31    7  22.58%   0
 manual/startup.texi   15    2  13.33%   0
manual/terminal.texi   24    2   8.33%   0
    manual/time.texi   33    2   6.06%   0
----
   manual/users.texi   66    0   0.00%   0
  manual/socket.texi   59    0   0.00%   0
  manual/signal.texi   27    0   0.00%   0
 manual/sysinfo.texi   22    0   0.00%   0
 manual/message.texi   12    0   0.00%   0
manual/platform.texi    8    0   0.00%   0
  manual/setjmp.texi    8    0   0.00%   0
  manual/syslog.texi    5    0   0.00%   0
    manual/pipe.texi    4    0   0.00%   0
 manual/threads.texi    2    0   0.00% 119
   manual/libdl.texi    0    0   0.00%   9
----
               Total 1068  717  67.13% 148

---

Alexandre Oliva (28):
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.
      Thread safety documentation.


 manual/argp.texi     |  181 +++++++++++++++++++
 manual/arith.texi    |  158 ++++++++++++++++
 manual/charset.texi  |   88 +++++++++
 manual/conf.texi     |   19 ++
 manual/crypt.texi    |   29 +++
 manual/ctype.texi    |   66 +++++++
 manual/debug.texi    |   18 ++
 manual/errno.texi    |   43 ++++
 manual/filesys.texi  |  221 +++++++++++++++++++++++
 manual/getopt.texi   |   29 +++
 manual/intro.texi    |  444 +++++++++++++++++++++++++++++++++++++++++++++
 manual/job.texi      |   27 +++
 manual/lang.texi     |   14 +
 manual/libdl.texi    |   10 +
 manual/llio.texi     |  255 ++++++++++++++++++++++++++
 manual/locale.texi   |  148 +++++++++++++++
 manual/macros.texi   |   42 ++++
 manual/math.texi     |  104 +++++++++++
 manual/memory.texi   |  456 +++++++++++++++++++++++++++++++++++++++++++++++
 manual/pattern.texi  |  489 ++++++++++++++++++++++++++++++++++++++++++++++++++
 manual/process.texi  |   20 ++
 manual/resource.texi |   16 ++
 manual/search.texi   |   11 +
 manual/startup.texi  |    8 +
 manual/stdio.texi    |  252 ++++++++++++++++++++++++++
 manual/string.texi   |  153 ++++++++++++++--
 manual/terminal.texi |    6 +
 manual/threads.texi  |  122 ++++++++++++
 manual/time.texi     |    7 +
 29 files changed, 3415 insertions(+), 21 deletions(-)
 create mode 100644 manual/libdl.texi

-- 
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