This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
[MTASCsft PATCH WIP4 00/28] MT-, AS- and AC-Safety docs
- From: Alexandre Oliva <aoliva at redhat dot com>
- To: libc-alpha at sourceware dot org
- Cc: carlos at redhat dot com, mtk dot manpages at gmail dot com
- Date: Sat, 12 Oct 2013 04:10:00 -0300
- Subject: [MTASCsft PATCH WIP4 00/28] MT-, AS- and AC-Safety docs
- Authentication-results: sourceware.org; auth=none
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