documentation for portable use of 'volatile'

[Paul Eggert]

Following up on
<http://lists.gnu.org/archive/html/bug-gnulib/2006-07/msg00048.html>,
address@hidden (Karl Berry) writes:

> could just include your text from these msgs pretty much as-is in
> the gnulib manual, where we don't attempt coherence :).

OK, but this particular topic is generic to C/C++, and isn't just a
gnulib issue.  So the Autoconf chapter "Portable C and C++
Programming" is probably a better home for it.  I installed the
following.  (I hope it's more coherent than my email was.  :-)

2006-07-05  Paul Eggert  <address@hidden>

        * doc/autoconf.texi (Volatile Objects): New section.

--- doc/autoconf.texi   28 Jun 2006 17:48:52 -0000      1.1055
+++ doc/autoconf.texi   5 Jul 2006 09:40:56 -0000       1.1056
@@ -513,6 +513,7 @@ Portable C and C++ Programming
 * Integer Overflow::            When integers get too large
 * Null Pointers::               Properties of null pointers
 * Buffer Overruns::             Subscript errors and the like
+* Volatile Objects::            @code{volatile} and signals
 * Floating Point Portability::  Portable floating-point arithmetic
 * Exiting Portably::            Exiting and the exit status
 
@@ -14679,6 +14680,7 @@ more information.
 * Integer Overflow::            When integers get too large
 * Null Pointers::               Properties of null pointers
 * Buffer Overruns::             Subscript errors and the like
+* Volatile Objects::            @code{volatile} and signals
 * Floating Point Portability::  Portable floating-point arithmetic
 * Exiting Portably::            Exiting and the exit status
 @end menu
@@ -14819,6 +14821,88 @@ implementations.  The @code{gets} functi
 invariably overflows its buffer when presented with an input line larger
 than the buffer.
 
address@hidden Volatile Objects
address@hidden Volatile Objects
address@hidden volatile objects
+
+The keyword @code{volatile} is often misunderstood in portable code.
+Its use inhibits some memory-access optimizations, but programmers often
+wish that it had a different meaning that it actually does.
+
+One area of confusion is the distinction between a volatile objects and
+volatile lvalues.  From the C standard's point of view, a volatile
+object has externally visible behavior.  You can think of such objects
+as having little oscilloscope probes attached to them, so that the user
+can observe every access to them, just as the user can observe data
+written to output files.  This is not true of ordinary objects accessed
+via volatile lvalues; only volatile objects can be observed by the user.
+Hence in general it does not help to use pointer-to-volatile to control
+access to ordinary objects.  For example:
+
address@hidden
+/* Declare and access a volatile object.
+   The keyword 'volatile' has an effect here.  */
+static int volatile x;
+x = 1;
+
+/* Access two ordinary objects via a volatile lvalue.
+   The keyword 'volatile' has no effect here.  */
+int y;
+int volatile *p;
+p = &y;
+*p = 1;
+p = malloc (sizeof (int));
+*p = 1;
address@hidden example
+
+Programmers often wish that @code{volatile} meant ``Perform the memory
+access here and now, without merging several memory accesses, without
+changing the memory word size width, and without reordering.''  But the
+C standard does not require this.  For volatile @emph{objects}, accesses
+must be done before the next sequence point; but otherwise merging,
+reordering, and word-size change is allowed.  Worse, in general volatile
address@hidden provide no more guarantees than nonvolatile lvalues, when
+the underlying objects are nonvolatile.
+
+Even when accessing volatile objects, the C standard allows only
+extremely limited signal handlers: the behavior is undefined if a signal
+handler reads any nonlocal object, or writes to any nonlocal object
+whose type is not @code{sig_atomic_t volatile}, or calls any standard
+library function other than @code{abort}, @code{signal}, and (if C99)
address@hidden  Hence C compilers do not need to worry about a signal
+disturbing ordinary computation, unless the computation accesses a
address@hidden volatile} object that is not a local variable.  Posix
+adds to the list of library functions callable from a portable signal
+handler, but otherwise is like the C standard in this area.
+
+Some C implementations allow memory-access optimizations within each
+translation unit, such that actual behavior agrees with the behavior
+required by the standard only when calling a function in some other
+translation unit, and a signal handler acts like it was called from a
+different translation unit.  The C standard hints that in these
+implementations, objects referred to by signal handlers ``would require
+explicit specification of @code{volatile} storage, as well as other
+implementation-defined restrictions.''  But unfortunately even for this
+special case these other restrictions are often not documented well.
address@hidden, , When is a Volatile Object Accessed?, gcc, Using the
address@hidden Compiler Collection (@acronym{GCC})}, for some
+restrictions imposed by @acronym{GCC}.  @xref{Defining Handlers, ,
+Defining Signal Handlers, libc, The @acronym{GNU} C Library}, for some
+restrictions imposed by the @acronym{GNU} C library.  Restrictions
+differ on other platforms.
+
+If possible, it is best to use a signal handler that fits within the
+limits imposed by the C and Posix standards.  If this is not practical,
+then a signal handler should access only volatile objects, and should
+not assume that volatile objects larger than a machine word have an
+internally consistent state.  If that is not practical either, then it
+may be difficult to write portable code, and it is not clear whether
+using volatile lvalues will help much.
+
+For @code{volatile}, C++ has the same problems that C does.
+Multithreaded applications have even more problems with @code{volatile},
+but they are beyond the scope of this section.
+
 @node Floating Point Portability
 @section Floating Point Portability
 @cindex floating point