Re: documentation for portable use of 'volatile'

[Ralf Wildenhues]

Hello Paul,

* Paul Eggert wrote on Wed, Jul 05, 2006 at 11:48:02AM CEST:
> 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.  :-)

If you keep going like this, and we don't destabilize CVS Autoconf much
in the near future, it would be beneficial to release another version in
a couple of months, simply for the improved documentation  :-)
(and some added bug fixes, of course).  Even more so with Bruno's
function portability section...

Some language nits inline (I don't feel qualified enough to comment on
the contents much).

> --- doc/autoconf.texi 28 Jun 2006 17:48:52 -0000      1.1055
> +++ doc/autoconf.texi 5 Jul 2006 09:40:56 -0000       1.1056

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

Shouldn't that be  s/meaning that/meaning than/  ?

> +
> +One area of confusion is the distinction between a volatile objects and

  s/ a //

> +volatile lvalues.  From the C standard's point of view, a volatile
*snip*

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

  s/general/&,/  ?

> address@hidden provide no more guarantees than nonvolatile lvalues, when
> +the underlying objects are nonvolatile.

Cheers,
Ralf