[doc,committed] clarify docs for function attribute "const"

I've checked in the attached patch for PR79738.

-Sandra

On 11/25/18 6:40 PM, Sandra Loosemore wrote:
> I've checked in the attached patch for PR79738.

I think we have lost something important with the clarification
of attribute const:

   The @code{const} attribute imposes greater restrictions on
   a function's definition than the similar @code{pure} attribute
   below because it additionally prohibits the function from reading
   memory except for constant global variables.

Permitting a const function to only read global constants means
it can't read local variables (including static const locals).
Something like the following should fix that:

   The @code{const} attribute prohibits a function from accessing
   objects whose value can change between successive invocations of
   the function.  Functions declared with the @code{const} attribute
   may access non-volatile constant objects with any storage duration.
   The attribute imposes greater restrictions on a function's definition
   than the similar @code{pure} attribute.

I have also removed the mention of global variables (since objects
at other scopes, including static locals or thread-local variables,
are also included) and instead of "reading" used the term "accessing"
since const functions can neither read nor write such objects.
  Finally, I've avoided describing the attribute in terms of pure
("additionally") and instead only mentioned pure for reference.

Let me know how this sounds.

Martin

On 11/26/18 10:17 AM, Martin Sebor wrote:
> On 11/25/18 6:40 PM, Sandra Loosemore wrote:
>> I've checked in the attached patch for PR79738.
> 
> I think we have lost something important with the clarification
> of attribute const:
> 
>    The @code{const} attribute imposes greater restrictions on
>    a function's definition than the similar @code{pure} attribute
>    below because it additionally prohibits the function from reading
>    memory except for constant global variables.
> 
> Permitting a const function to only read global constants means
> it can't read local variables (including static const locals).
> Something like the following should fix that:
> 
>    The @code{const} attribute prohibits a function from accessing
>    objects whose value can change between successive invocations of
>    the function.  Functions declared with the @code{const} attribute
>    may access non-volatile constant objects with any storage duration.
>    The attribute imposes greater restrictions on a function's definition
>    than the similar @code{pure} attribute.
> 
> I have also removed the mention of global variables (since objects
> at other scopes, including static locals or thread-local variables,
> are also included) and instead of "reading" used the term "accessing"
> since const functions can neither read nor write such objects.
>   Finally, I've avoided describing the attribute in terms of pure
> ("additionally") and instead only mentioned pure for reference.
> 
> Let me know how this sounds.

Hmmm.  If we go with this wording, then the description of "pure" needs 
to be updated too, since it also uses the "constant global variables" 
language now to describe how it differs from "pure".  I think we do need 
some succinct summary of exactly how the two attributes differ to 
explain why it is an error to provide both attributes and help users 
choose which is more appropriate.  Using parallel language except in the 
particulars that differ is one way to accomplish that.

I admit I really struggled with the wording in coming up with the 
previous patch....  :-(  I thought I understood the difference, but I 
guess not.  :-(

-Sandra

On 11/26/18 11:13 AM, Sandra Loosemore wrote:
> On 11/26/18 10:17 AM, Martin Sebor wrote:
>> On 11/25/18 6:40 PM, Sandra Loosemore wrote:
>>> I've checked in the attached patch for PR79738.
>>
>> I think we have lost something important with the clarification
>> of attribute const:
>>
>>    The @code{const} attribute imposes greater restrictions on
>>    a function's definition than the similar @code{pure} attribute
>>    below because it additionally prohibits the function from reading
>>    memory except for constant global variables.
>>
>> Permitting a const function to only read global constants means
>> it can't read local variables (including static const locals).
>> Something like the following should fix that:
>>
>>    The @code{const} attribute prohibits a function from accessing
>>    objects whose value can change between successive invocations of
>>    the function.  Functions declared with the @code{const} attribute
>>    may access non-volatile constant objects with any storage duration.
>>    The attribute imposes greater restrictions on a function's definition
>>    than the similar @code{pure} attribute.
>>
>> I have also removed the mention of global variables (since objects
>> at other scopes, including static locals or thread-local variables,
>> are also included) and instead of "reading" used the term "accessing"
>> since const functions can neither read nor write such objects.
>>   Finally, I've avoided describing the attribute in terms of pure
>> ("additionally") and instead only mentioned pure for reference.
>>
>> Let me know how this sounds.
> 
> Hmmm.  If we go with this wording, then the description of "pure" needs 
> to be updated too, since it also uses the "constant global variables" 
> language now to describe how it differs from "pure".  I think we do need 
> some succinct summary of exactly how the two attributes differ to 
> explain why it is an error to provide both attributes and help users 
> choose which is more appropriate.  Using parallel language except in the 
> particulars that differ is one way to accomplish that.
> 
> I admit I really struggled with the wording in coming up with the 
> previous patch....  :-(  I thought I understood the difference, but I 
> guess not.  :-(

I agree that both const and pure should be updated as well.  Let
me put together a patch for both.

Martin

On 11/26/18 8:32 PM, Martin Sebor wrote:
> On 11/26/18 11:13 AM, Sandra Loosemore wrote:
>> On 11/26/18 10:17 AM, Martin Sebor wrote:
>>> On 11/25/18 6:40 PM, Sandra Loosemore wrote:
>>>> I've checked in the attached patch for PR79738.
>>>
>>> I think we have lost something important with the clarification
>>> of attribute const:
>>>
>>>    The @code{const} attribute imposes greater restrictions on
>>>    a function's definition than the similar @code{pure} attribute
>>>    below because it additionally prohibits the function from reading
>>>    memory except for constant global variables.
>>>
>>> Permitting a const function to only read global constants means
>>> it can't read local variables (including static const locals).
>>> Something like the following should fix that:
>>>
>>>    The @code{const} attribute prohibits a function from accessing
>>>    objects whose value can change between successive invocations of
>>>    the function.  Functions declared with the @code{const} attribute
>>>    may access non-volatile constant objects with any storage duration.
>>>    The attribute imposes greater restrictions on a function's definition
>>>    than the similar @code{pure} attribute.
>>>
>>> I have also removed the mention of global variables (since objects
>>> at other scopes, including static locals or thread-local variables,
>>> are also included) and instead of "reading" used the term "accessing"
>>> since const functions can neither read nor write such objects.
>>>   Finally, I've avoided describing the attribute in terms of pure
>>> ("additionally") and instead only mentioned pure for reference.
>>>
>>> Let me know how this sounds.
>>
>> Hmmm.  If we go with this wording, then the description of "pure" 
>> needs to be updated too, since it also uses the "constant global 
>> variables" language now to describe how it differs from "pure".  I 
>> think we do need some succinct summary of exactly how the two 
>> attributes differ to explain why it is an error to provide both 
>> attributes and help users choose which is more appropriate.  Using 
>> parallel language except in the particulars that differ is one way to 
>> accomplish that.
>>
>> I admit I really struggled with the wording in coming up with the 
>> previous patch....  :-(  I thought I understood the difference, but I 
>> guess not.  :-(
> 
> I agree that both const and pure should be updated as well.  Let
> me put together a patch for both.

Thanks.  I was going to take another stab at it myself after finishing 
some other stuff in my queue, but I'll wait and see what you suggest.

-Sandra

On 11/26/18 8:45 PM, Sandra Loosemore wrote:
> On 11/26/18 8:32 PM, Martin Sebor wrote:
>> On 11/26/18 11:13 AM, Sandra Loosemore wrote:
>>> On 11/26/18 10:17 AM, Martin Sebor wrote:
>>>> On 11/25/18 6:40 PM, Sandra Loosemore wrote:
>>>>> I've checked in the attached patch for PR79738.
>>>>
>>>> I think we have lost something important with the clarification
>>>> of attribute const:
>>>>
>>>>    The @code{const} attribute imposes greater restrictions on
>>>>    a function's definition than the similar @code{pure} attribute
>>>>    below because it additionally prohibits the function from reading
>>>>    memory except for constant global variables.
>>>>
>>>> Permitting a const function to only read global constants means
>>>> it can't read local variables (including static const locals).
>>>> Something like the following should fix that:
>>>>
>>>>    The @code{const} attribute prohibits a function from accessing
>>>>    objects whose value can change between successive invocations of
>>>>    the function.  Functions declared with the @code{const} attribute
>>>>    may access non-volatile constant objects with any storage duration.
>>>>    The attribute imposes greater restrictions on a function's 
>>>> definition
>>>>    than the similar @code{pure} attribute.
>>>>
>>>> I have also removed the mention of global variables (since objects
>>>> at other scopes, including static locals or thread-local variables,
>>>> are also included) and instead of "reading" used the term "accessing"
>>>> since const functions can neither read nor write such objects.
>>>>   Finally, I've avoided describing the attribute in terms of pure
>>>> ("additionally") and instead only mentioned pure for reference.
>>>>
>>>> Let me know how this sounds.
>>>
>>> Hmmm.  If we go with this wording, then the description of "pure" 
>>> needs to be updated too, since it also uses the "constant global 
>>> variables" language now to describe how it differs from "pure".  I 
>>> think we do need some succinct summary of exactly how the two 
>>> attributes differ to explain why it is an error to provide both 
>>> attributes and help users choose which is more appropriate.  Using 
>>> parallel language except in the particulars that differ is one way to 
>>> accomplish that.
>>>
>>> I admit I really struggled with the wording in coming up with the 
>>> previous patch....  :-(  I thought I understood the difference, but I 
>>> guess not.  :-(
>>
>> I agree that both const and pure should be updated as well.  Let
>> me put together a patch for both.
> 
> Thanks.  I was going to take another stab at it myself after finishing 
> some other stuff in my queue, but I'll wait and see what you suggest.

Attached is my proposed update.  The user's email suggested going
into a lot of detail that I'm not sure would be helpful.  I think
it's safer to keep it simple than to try to carefully outline tricky
conditions under which some const or pure functions might get away
with modifying program state.  At the same time, I tried not to
outright prohibit it so I phrased the restrictions in terms of
observable program state (as opposed to reading or writing
"global" variables and such).

I also made a few other changes, like move the example of
the square function from pure to const (since the function is
much more likely const), and made the const restrictions stand
on their own, rather than depending on pure.

Martin
PR 79738 - Documentation for __attribute__((const)) slightly misleading

	* doc/extend.texi (attribute const, pure): Clarify.

Index: /ssd/src/gcc/svn/gcc/doc/extend.texi
===================================================================
--- /ssd/src/gcc/svn/gcc/doc/extend.texi	(revision 266760)
+++ /ssd/src/gcc/svn/gcc/doc/extend.texi	(working copy)
@@ -2518,25 +2518,45 @@ are automatically detected and this attribute is i
 @item const
 @cindex @code{const} function attribute
 @cindex functions that have no side effects
-Many functions do not examine any values except their arguments, and
-have no effects except to return a value.  Calls to such functions lend
-themselves to optimization such as common subexpression elimination.
-The presence of the @code{const} attribute on a function declaration 
-allows GCC to emit more efficient code for some calls to the function.  
+Calls to functions whose return value is not affected by changes to
+the observable state of the program and that have no observable effects
+on such state other than to return a value may lend themselves to
+optimizations such as common subexpression elimination.  Declaring such
+functions with the @code{const} attribute allows GCC to emit more efficient
+code for consecutive calls to the function.
 
+The @code{const} attribute prohibits a function from reading objects
+that affect its return value between successive invocations.  However,
+functions declared with the attribute can safely read objects that do
+not affect their return value, such as non-volatile constants.
 The @code{const} attribute imposes greater restrictions on a function's
-definition than the similar @code{pure} attribute below because it
-additionally prohibits the function from reading memory except for
-constant global variables.  Decorating the same function with
-both the @code{const} and the @code{pure} attribute is diagnosed.
+definition than the similar @code{pure} attribute.  Declaring the same
+function with both the @code{const} and the @code{pure} attribute is
+diagnosed.  Because a const function cannot have any observable side
+effects it does not make sense for it to return @code{void}.  Declaring
+such a function is diagnosed.
 
+For example,
+
+@smallexample
+int square (int) __attribute__ ((const));
+@end smallexample
+
+@noindent
+tells GCC that subsequent calls to function @code{square} with the same
+argument value can be replaced by the result of the first call regardless
+of the statements in between.
+
 @cindex pointer arguments
 Note that a function that has pointer arguments and examines the data
-pointed to must @emph{not} be declared @code{const}.  Likewise, a
-function that calls a non-@code{const} function usually must not be
-@code{const}.  Because a @code{const} function cannot have any side
-effects it does not make sense for such a function to return @code{void}.
-Declaring such a function is diagnosed.
+pointed to must @emph{not} be declared @code{const} if the pointed-to
+data might change between successive invocations of the function.  In
+general, since a function cannot distinguish data that might change
+from data that cannot, @code{const} functions should never be
+pass-by-reference.  Likewise, a function that calls a non-@code{const}
+function usually must not be @code{const}.  Because a @code{const}
+function cannot have any side effects it does not make sense for such
+a function to return @code{void}. Declaring such a function is diagnosed.
 
 @item constructor
 @itemx destructor
@@ -3301,34 +3321,51 @@ to prevent recursion.
 @item pure
 @cindex @code{pure} function attribute
 @cindex functions that have no side effects
-Many functions have no effects except the return value and their
-return value depends only on the parameters and/or global variables.
-Calls to such functions can be subject
-to common subexpression elimination and loop optimization just as an
-arithmetic operator would be.  These functions should be declared
-with the attribute @code{pure}.  For example,
 
+Calls to functions that have no observable effects on the state of
+the program other than to return a value may lend themselves to optimizations
+such as common subexpression elimination.  Declaring such functions with
+the @code{pure} attribute allows GCC to emit more efficient code for
+consecutive calls to the function.
+
+The @code{pure} attribute prohibits a function from modifying the state
+of the program that is observable by means other than inspecting
+the function's return value.  However, functions declared with the @code{pure}
+attribute can safely read any non-volatile objects, and modify the value of
+objects in a way that does not affect their return value or the observable
+state of the program.  Declaring the same function with both the @code{const}
+and the @code{pure} attribute is diagnosed.
+
+For example,
+
 @smallexample
-int square (int) __attribute__ ((pure));
+int hash (char *) __attribute__ ((pure));
 @end smallexample
 
 @noindent
-says that the hypothetical function @code{square} is safe to call
-fewer times than the program says.
+tells GCC that subsequent calls to the function @code{hash} with the same
+string can be replaced by the result of the first call provided the state
+of the program observable by @code{hash}, including the contents of the array
+itself, does not change in between.  Even though @code{hash} takes a non-const
+pointer argument it must not modify the array it points to, or any other object
+whose value the rest of the program may depend on.  However, making changes to
+the array between successive calls to the function is permitted.  The restriction
+also applies to member objects referenced by the @code{this} pointer in C++
+non-static member functions.
 
 Some common examples of pure functions are @code{strlen} or @code{memcmp}.
 Interesting non-pure functions are functions with infinite loops or those
 depending on volatile memory or other system resource, that may change between
-two consecutive calls (such as @code{feof} in a multithreading environment).
+consecutive calls (such as the @code{feof} function in a multithreading
+environment).
 
 The @code{pure} attribute imposes similar but looser restrictions on
 a function's definition than the @code{const} attribute: @code{pure}
-allows the function to read any non-volatile memory, not just
-constant global variables.  Decorating the same function with
-both the @code{pure} and the @code{const} attribute is diagnosed.
-Because a @code{pure} function cannot have any side effects it does not
-make sense for such a function to return @code{void}.  Declaring such
-a function is diagnosed.
+allows the function to read any non-volatile memory.  Declaring
+the same function with both the @code{pure} and the @code{const} attribute
+is diagnosed.  Because a pure function cannot have any observable side effects
+it does not make sense for such a function to return @code{void}.  Declaring
+such a function is diagnosed.
 
 @item returns_nonnull
 @cindex @code{returns_nonnull} function attribute

On 12/3/18 2:47 PM, Martin Sebor wrote:
> [snip]
> 
> Attached is my proposed update.  The user's email suggested going
> into a lot of detail that I'm not sure would be helpful.  I think
> it's safer to keep it simple than to try to carefully outline tricky
> conditions under which some const or pure functions might get away
> with modifying program state.  At the same time, I tried not to
> outright prohibit it so I phrased the restrictions in terms of
> observable program state (as opposed to reading or writing
> "global" variables and such).
> 
> I also made a few other changes, like move the example of
> the square function from pure to const (since the function is
> much more likely const), and made the const restrictions stand
> on their own, rather than depending on pure.

> Index: /ssd/src/gcc/svn/gcc/doc/extend.texi
> ===================================================================
> --- /ssd/src/gcc/svn/gcc/doc/extend.texi	(revision 266760)
> +++ /ssd/src/gcc/svn/gcc/doc/extend.texi	(working copy)
> @@ -2518,25 +2518,45 @@ are automatically detected and this attribute is i
>  @item const
>  @cindex @code{const} function attribute
>  @cindex functions that have no side effects
> -Many functions do not examine any values except their arguments, and
> -have no effects except to return a value.  Calls to such functions lend
> -themselves to optimization such as common subexpression elimination.
> -The presence of the @code{const} attribute on a function declaration 
> -allows GCC to emit more efficient code for some calls to the function.  
> +Calls to functions whose return value is not affected by changes to
> +the observable state of the program and that have no observable effects
> +on such state other than to return a value may lend themselves to
> +optimizations such as common subexpression elimination.  Declaring such
> +functions with the @code{const} attribute allows GCC to emit more efficient
> +code for consecutive calls to the function.

I don't think the calls have to be consecutive for GCC to emit more 
efficient code.  I'd kill that last bit.

> +The @code{const} attribute prohibits a function from reading objects
> +that affect its return value between successive invocations.  However,
> +functions declared with the attribute can safely read objects that do
> +not affect their return value, such as non-volatile constants.
>  The @code{const} attribute imposes greater restrictions on a function's
> -definition than the similar @code{pure} attribute below because it
> -additionally prohibits the function from reading memory except for
> -constant global variables.  Decorating the same function with
> -both the @code{const} and the @code{pure} attribute is diagnosed.
> +definition than the similar @code{pure} attribute.  Declaring the same
> +function with both the @code{const} and the @code{pure} attribute is
> +diagnosed.  Because a const function cannot have any observable side

@code{const}

> +effects it does not make sense for it to return @code{void}.  Declaring
> +such a function is diagnosed.
>  
> +For example,
> +
> +@smallexample
> +int square (int) __attribute__ ((const));
> +@end smallexample
> +
> +@noindent
> +tells GCC that subsequent calls to function @code{square} with the same
> +argument value can be replaced by the result of the first call regardless
> +of the statements in between.
> +

I think it would be better to move this example immediately after the 
first paragraph, before you digress about the diagnostics and such like.

>  @cindex pointer arguments
>  Note that a function that has pointer arguments and examines the data
> -pointed to must @emph{not} be declared @code{const}.  Likewise, a
> -function that calls a non-@code{const} function usually must not be
> -@code{const}.  Because a @code{const} function cannot have any side
> -effects it does not make sense for such a function to return @code{void}.
> -Declaring such a function is diagnosed.
> +pointed to must @emph{not} be declared @code{const} if the pointed-to
> +data might change between successive invocations of the function.  In
> +general, since a function cannot distinguish data that might change
> +from data that cannot, @code{const} functions should never be
> +pass-by-reference.  Likewise, a function that calls a non-@code{const}

I don't understand what a pass-by-reference function might be.  Do you 
mean it should not have reference parameters in C++?

> +function usually must not be @code{const}.  Because a @code{const}
> +function cannot have any side effects it does not make sense for such
> +a function to return @code{void}. Declaring such a function is diagnosed.

The last two sentences duplicate what you say a couple paragraphs 
earlier.  We only need to say this once.  :-)

>  
>  @item constructor
>  @itemx destructor
> @@ -3301,34 +3321,51 @@ to prevent recursion.
>  @item pure
>  @cindex @code{pure} function attribute
>  @cindex functions that have no side effects
> -Many functions have no effects except the return value and their
> -return value depends only on the parameters and/or global variables.
> -Calls to such functions can be subject
> -to common subexpression elimination and loop optimization just as an
> -arithmetic operator would be.  These functions should be declared
> -with the attribute @code{pure}.  For example,
>  
> +Calls to functions that have no observable effects on the state of
> +the program other than to return a value may lend themselves to optimizations
> +such as common subexpression elimination.  Declaring such functions with
> +the @code{pure} attribute allows GCC to emit more efficient code for
> +consecutive calls to the function.

Same complaint about "consecutive" as above.

> +
> +The @code{pure} attribute prohibits a function from modifying the state
> +of the program that is observable by means other than inspecting
> +the function's return value.  However, functions declared with the @code{pure}
> +attribute can safely read any non-volatile objects, and modify the value of
> +objects in a way that does not affect their return value or the observable
> +state of the program.  Declaring the same function with both the @code{const}
> +and the @code{pure} attribute is diagnosed.
> +
> +For example,
> +
>  @smallexample
> -int square (int) __attribute__ ((pure));
> +int hash (char *) __attribute__ ((pure));
>  @end smallexample
>  
>  @noindent
> -says that the hypothetical function @code{square} is safe to call
> -fewer times than the program says.
> +tells GCC that subsequent calls to the function @code{hash} with the same
> +string can be replaced by the result of the first call provided the state
> +of the program observable by @code{hash}, including the contents of the array
> +itself, does not change in between.  Even though @code{hash} takes a non-const

non-@code{const}

> +pointer argument it must not modify the array it points to, or any other object
> +whose value the rest of the program may depend on.  However, making changes to
> +the array between successive calls to the function is permitted.  The restriction

That "making changes" language is confusing.  Can we put that sentence 
in a more active voice, like "Other parts of the program can make 
changes to the array."?

> +also applies to member objects referenced by the @code{this} pointer in C++
> +non-static member functions.
>  
>  Some common examples of pure functions are @code{strlen} or @code{memcmp}.
>  Interesting non-pure functions are functions with infinite loops or those
>  depending on volatile memory or other system resource, that may change between
> -two consecutive calls (such as @code{feof} in a multithreading environment).
> +consecutive calls (such as the @code{feof} function in a multithreading
> +environment).
>  
>  The @code{pure} attribute imposes similar but looser restrictions on
>  a function's definition than the @code{const} attribute: @code{pure}
> -allows the function to read any non-volatile memory, not just
> -constant global variables.  Decorating the same function with
> -both the @code{pure} and the @code{const} attribute is diagnosed.
> -Because a @code{pure} function cannot have any side effects it does not
> -make sense for such a function to return @code{void}.  Declaring such
> -a function is diagnosed.
> +allows the function to read any non-volatile memory.  Declaring
> +the same function with both the @code{pure} and the @code{const} attribute
> +is diagnosed.  Because a pure function cannot have any observable side effects
> +it does not make sense for such a function to return @code{void}.  Declaring
> +such a function is diagnosed.

Again, those last two sentences duplicate what you already said a couple 
paragraphs up.

>  
>  @item returns_nonnull
>  @cindex @code{returns_nonnull} function attribute

-Sandra

On 12/3/18 11:04 PM, Sandra Loosemore wrote:
> On 12/3/18 2:47 PM, Martin Sebor wrote:
>> [snip]
>>
>> Attached is my proposed update.  The user's email suggested going
>> into a lot of detail that I'm not sure would be helpful.  I think
>> it's safer to keep it simple than to try to carefully outline tricky
>> conditions under which some const or pure functions might get away
>> with modifying program state.  At the same time, I tried not to
>> outright prohibit it so I phrased the restrictions in terms of
>> observable program state (as opposed to reading or writing
>> "global" variables and such).
>>
>> I also made a few other changes, like move the example of
>> the square function from pure to const (since the function is
>> much more likely const), and made the const restrictions stand
>> on their own, rather than depending on pure.
> 
>> Index: /ssd/src/gcc/svn/gcc/doc/extend.texi
>> ===================================================================
>> --- /ssd/src/gcc/svn/gcc/doc/extend.texi    (revision 266760)
>> +++ /ssd/src/gcc/svn/gcc/doc/extend.texi    (working copy)
>> @@ -2518,25 +2518,45 @@ are automatically detected and this attribute 
>> is i
>>  @item const
>>  @cindex @code{const} function attribute
>>  @cindex functions that have no side effects
>> -Many functions do not examine any values except their arguments, and
>> -have no effects except to return a value.  Calls to such functions lend
>> -themselves to optimization such as common subexpression elimination.
>> -The presence of the @code{const} attribute on a function declaration 
>> -allows GCC to emit more efficient code for some calls to the 
>> function. +Calls to functions whose return value is not affected by 
>> changes to
>> +the observable state of the program and that have no observable effects
>> +on such state other than to return a value may lend themselves to
>> +optimizations such as common subexpression elimination.  Declaring such
>> +functions with the @code{const} attribute allows GCC to emit more 
>> efficient
>> +code for consecutive calls to the function.
> 
> I don't think the calls have to be consecutive for GCC to emit more 
> efficient code.  I'd kill that last bit.

I added it because I want to make it clear that the attribute
shouldn't be expected to improve the efficiency of any single
call.  It can only improve it for the second (and subsequent)
call with the same argument values as the first.  I've tweaked
the sentence a bit.

> 
>> +The @code{const} attribute prohibits a function from reading objects
>> +that affect its return value between successive invocations.  However,
>> +functions declared with the attribute can safely read objects that do
>> +not affect their return value, such as non-volatile constants.
>>  The @code{const} attribute imposes greater restrictions on a function's
>> -definition than the similar @code{pure} attribute below because it
>> -additionally prohibits the function from reading memory except for
>> -constant global variables.  Decorating the same function with
>> -both the @code{const} and the @code{pure} attribute is diagnosed.
>> +definition than the similar @code{pure} attribute.  Declaring the same
>> +function with both the @code{const} and the @code{pure} attribute is
>> +diagnosed.  Because a const function cannot have any observable side
> 
> @code{const}

I actually meant to bring this up separately.

I don't think @code would be appropriate in this context.  It's
not a use of the attribute name but rather a description of
the function.  Analogous to "a const pointer" or "a volatile
access" vs "a @code{const}-qualified pointer or
"the @code{volatile} qualifier."  I think the manual already
uses this style, albeit not completely consistently.  The C
and C++ standards aren't 100% consistent either, but I believe
the editors follow this principle when they think of it.  Unless
you really do think GCC should go the other way around I would
like to add this to the GCC style guidelines and fix
the inconsistencies.

I thought I was consistent in this in my own changes but I see
I was not.  I've changed the @code{const} to just const according
to the above.

>> +effects it does not make sense for it to return @code{void}.  Declaring
>> +such a function is diagnosed.
>>
>> +For example,
>> +
>> +@smallexample
>> +int square (int) __attribute__ ((const));
>> +@end smallexample
>> +
>> +@noindent
>> +tells GCC that subsequent calls to function @code{square} with the same
>> +argument value can be replaced by the result of the first call 
>> regardless
>> +of the statements in between.
>> +
> 
> I think it would be better to move this example immediately after the 
> first paragraph, before you digress about the diagnostics and such like.

Done.

> 
>>  @cindex pointer arguments
>>  Note that a function that has pointer arguments and examines the data
>> -pointed to must @emph{not} be declared @code{const}.  Likewise, a
>> -function that calls a non-@code{const} function usually must not be
>> -@code{const}.  Because a @code{const} function cannot have any side
>> -effects it does not make sense for such a function to return 
>> @code{void}.
>> -Declaring such a function is diagnosed.
>> +pointed to must @emph{not} be declared @code{const} if the pointed-to
>> +data might change between successive invocations of the function.  In
>> +general, since a function cannot distinguish data that might change
>> +from data that cannot, @code{const} functions should never be
>> +pass-by-reference.  Likewise, a function that calls a non-@code{const}
> 
> I don't understand what a pass-by-reference function might be.  Do you 
> mean it should not have reference parameters in C++?

Yes.  I've clarified it a bit.

> 
>> +function usually must not be @code{const}.  Because a @code{const}
>> +function cannot have any side effects it does not make sense for such
>> +a function to return @code{void}. Declaring such a function is 
>> diagnosed.
> 
> The last two sentences duplicate what you say a couple paragraphs 
> earlier.  We only need to say this once.  :-)

Ah, right, thank you.

> 
>>
>>  @item constructor
>>  @itemx destructor
>> @@ -3301,34 +3321,51 @@ to prevent recursion.
>>  @item pure
>>  @cindex @code{pure} function attribute
>>  @cindex functions that have no side effects
>> -Many functions have no effects except the return value and their
>> -return value depends only on the parameters and/or global variables.
>> -Calls to such functions can be subject
>> -to common subexpression elimination and loop optimization just as an
>> -arithmetic operator would be.  These functions should be declared
>> -with the attribute @code{pure}.  For example,
>>
>> +Calls to functions that have no observable effects on the state of
>> +the program other than to return a value may lend themselves to 
>> optimizations
>> +such as common subexpression elimination.  Declaring such functions with
>> +the @code{pure} attribute allows GCC to emit more efficient code for
>> +consecutive calls to the function.
> 
> Same complaint about "consecutive" as above.

I've adjusted this sentence as well.

> 
>> +
>> +The @code{pure} attribute prohibits a function from modifying the state
>> +of the program that is observable by means other than inspecting
>> +the function's return value.  However, functions declared with the 
>> @code{pure}
>> +attribute can safely read any non-volatile objects, and modify the 
>> value of
>> +objects in a way that does not affect their return value or the 
>> observable
>> +state of the program.  Declaring the same function with both the 
>> @code{const}
>> +and the @code{pure} attribute is diagnosed.
>> +
>> +For example,
>> +
>>  @smallexample
>> -int square (int) __attribute__ ((pure));
>> +int hash (char *) __attribute__ ((pure));
>>  @end smallexample
>>
>>  @noindent
>> -says that the hypothetical function @code{square} is safe to call
>> -fewer times than the program says.
>> +tells GCC that subsequent calls to the function @code{hash} with the 
>> same
>> +string can be replaced by the result of the first call provided the 
>> state
>> +of the program observable by @code{hash}, including the contents of 
>> the array
>> +itself, does not change in between.  Even though @code{hash} takes a 
>> non-const
> 
> non-@code{const}
> 
>> +pointer argument it must not modify the array it points to, or any 
>> other object
>> +whose value the rest of the program may depend on.  However, making 
>> changes to
>> +the array between successive calls to the function is permitted.  The 
>> restriction
> 
> That "making changes" language is confusing.  Can we put that sentence 
> in a more active voice, like "Other parts of the program can make 
> changes to the array."?

Adjusted.

> 
>> +also applies to member objects referenced by the @code{this} pointer 
>> in C++
>> +non-static member functions.
>>
>>  Some common examples of pure functions are @code{strlen} or 
>> @code{memcmp}.
>>  Interesting non-pure functions are functions with infinite loops or 
>> those
>>  depending on volatile memory or other system resource, that may 
>> change between
>> -two consecutive calls (such as @code{feof} in a multithreading 
>> environment).
>> +consecutive calls (such as the @code{feof} function in a multithreading
>> +environment).
>>
>>  The @code{pure} attribute imposes similar but looser restrictions on
>>  a function's definition than the @code{const} attribute: @code{pure}
>> -allows the function to read any non-volatile memory, not just
>> -constant global variables.  Decorating the same function with
>> -both the @code{pure} and the @code{const} attribute is diagnosed.
>> -Because a @code{pure} function cannot have any side effects it does not
>> -make sense for such a function to return @code{void}.  Declaring such
>> -a function is diagnosed.
>> +allows the function to read any non-volatile memory.  Declaring
>> +the same function with both the @code{pure} and the @code{const} 
>> attribute
>> +is diagnosed.  Because a pure function cannot have any observable 
>> side effects
>> +it does not make sense for such a function to return @code{void}.  
>> Declaring
>> +such a function is diagnosed.
> 
> Again, those last two sentences duplicate what you already said a couple 
> paragraphs up.

Fixed.

Martin
PR 79738 - Documentation for __attribute__((const)) slightly misleading

	* doc/extend.texi (attribute const, pure): Clarify.

Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi	(revision 266881)
+++ gcc/doc/extend.texi	(working copy)
@@ -2578,25 +2578,46 @@ are automatically detected and this attribute is i
 @item const
 @cindex @code{const} function attribute
 @cindex functions that have no side effects
-Many functions do not examine any values except their arguments, and
-have no effects except to return a value.  Calls to such functions lend
-themselves to optimization such as common subexpression elimination.
-The presence of the @code{const} attribute on a function declaration 
-allows GCC to emit more efficient code for some calls to the function.  
+Calls to functions whose return value is not affected by changes to
+the observable state of the program and that have no observable effects
+on such state other than to return a value may lend themselves to
+optimizations such as common subexpression elimination.  Declaring such
+functions with the @code{const} attribute allows GCC to avoid emitting
+some calls in repeated invocations of the function with the same argument
+values.
 
+For example,
+
+@smallexample
+int square (int) __attribute__ ((const));
+@end smallexample
+
+@noindent
+tells GCC that subsequent calls to function @code{square} with the same
+argument value can be replaced by the result of the first call regardless
+of the statements in between.
+
+The @code{const} attribute prohibits a function from reading objects
+that affect its return value between successive invocations.  However,
+functions declared with the attribute can safely read objects that do
+not change their return value, such as non-volatile constants.
+
 The @code{const} attribute imposes greater restrictions on a function's
-definition than the similar @code{pure} attribute below because it
-additionally prohibits the function from reading memory except for
-constant global variables.  Decorating the same function with
-both the @code{const} and the @code{pure} attribute is diagnosed.
+definition than the similar @code{pure} attribute.  Declaring the same
+function with both the @code{const} and the @code{pure} attribute is
+diagnosed.  Because a const function cannot have any observable side
+effects it does not make sense for it to return @code{void}.  Declaring
+such a function is diagnosed.
 
 @cindex pointer arguments
 Note that a function that has pointer arguments and examines the data
-pointed to must @emph{not} be declared @code{const}.  Likewise, a
-function that calls a non-@code{const} function usually must not be
-@code{const}.  Because a @code{const} function cannot have any side
-effects it does not make sense for such a function to return @code{void}.
-Declaring such a function is diagnosed.
+pointed to must @emph{not} be declared @code{const} if the pointed-to
+data might change between successive invocations of the function.  In
+general, since a function cannot distinguish data that might change
+from data that cannot, const functions should never be
+pass-by-reference (take pointer or, in C++, reference arguments).
+Likewise, a function that calls a non-const function usually must not
+be const itself.
 
 @item constructor
 @itemx destructor
@@ -3361,34 +3382,52 @@ to prevent recursion.
 @item pure
 @cindex @code{pure} function attribute
 @cindex functions that have no side effects
-Many functions have no effects except the return value and their
-return value depends only on the parameters and/or global variables.
-Calls to such functions can be subject
-to common subexpression elimination and loop optimization just as an
-arithmetic operator would be.  These functions should be declared
-with the attribute @code{pure}.  For example,
 
+Calls to functions that have no observable effects on the state of
+the program other than to return a value may lend themselves to optimizations
+such as common subexpression elimination.  Declaring such functions with
+the @code{pure} attribute allows GCC to avoid emitting some calls in repeated
+invocations of the function with the same argument values.
+
+The @code{pure} attribute prohibits a function from modifying the state
+of the program that is observable by means other than inspecting
+the function's return value.  However, functions declared with the @code{pure}
+attribute can safely read any non-volatile objects, and modify the value of
+objects in a way that does not affect their return value or the observable
+state of the program.
+
+For example,
+
 @smallexample
-int square (int) __attribute__ ((pure));
+int hash (char *) __attribute__ ((pure));
 @end smallexample
 
 @noindent
-says that the hypothetical function @code{square} is safe to call
-fewer times than the program says.
+tells GCC that subsequent calls to the function @code{hash} with the same
+string can be replaced by the result of the first call provided the state
+of the program observable by @code{hash}, including the contents of the array
+itself, does not change in between.  Even though @code{hash} takes a non-const
+pointer argument it must not modify the array it points to, or any other object
+whose value the rest of the program may depend on.  However, the caller may
+safely change the contents of the array between successive calls to
+the function (doing so disables the optimization).  The restriction also
+applies to member objects referenced by the @code{this} pointer in C++
+non-static member functions.
 
 Some common examples of pure functions are @code{strlen} or @code{memcmp}.
 Interesting non-pure functions are functions with infinite loops or those
 depending on volatile memory or other system resource, that may change between
-two consecutive calls (such as @code{feof} in a multithreading environment).
+consecutive calls (such as the standard C @code{feof} function in
+a multithreading environment).
 
 The @code{pure} attribute imposes similar but looser restrictions on
 a function's definition than the @code{const} attribute: @code{pure}
-allows the function to read any non-volatile memory, not just
-constant global variables.  Decorating the same function with
-both the @code{pure} and the @code{const} attribute is diagnosed.
-Because a @code{pure} function cannot have any side effects it does not
-make sense for such a function to return @code{void}.  Declaring such
-a function is diagnosed.
+allows the function to read any non-volatile memory, even if it changes
+in between successive invocations of the function.  Declaring the same
+function with both the @code{pure} and the @code{const} attribute is
+diagnosed.  Because a pure function cannot have any observable side
+effects it does not make sense for such a function to return @code{void}.
+Declaring such a function is diagnosed.
 
 @item returns_nonnull
 @cindex @code{returns_nonnull} function attribute

Ping: https://gcc.gnu.org/ml/gcc-patches/2018-12/msg00426.html

(I have now committed the @code{const} cleanup mentioned below.)

On 12/6/18 6:12 PM, Martin Sebor wrote:
> On 12/3/18 11:04 PM, Sandra Loosemore wrote:
>> On 12/3/18 2:47 PM, Martin Sebor wrote:
>>> [snip]
>>>
>>> Attached is my proposed update.  The user's email suggested going
>>> into a lot of detail that I'm not sure would be helpful.  I think
>>> it's safer to keep it simple than to try to carefully outline tricky
>>> conditions under which some const or pure functions might get away
>>> with modifying program state.  At the same time, I tried not to
>>> outright prohibit it so I phrased the restrictions in terms of
>>> observable program state (as opposed to reading or writing
>>> "global" variables and such).
>>>
>>> I also made a few other changes, like move the example of
>>> the square function from pure to const (since the function is
>>> much more likely const), and made the const restrictions stand
>>> on their own, rather than depending on pure.
>>
>>> Index: /ssd/src/gcc/svn/gcc/doc/extend.texi
>>> ===================================================================
>>> --- /ssd/src/gcc/svn/gcc/doc/extend.texi    (revision 266760)
>>> +++ /ssd/src/gcc/svn/gcc/doc/extend.texi    (working copy)
>>> @@ -2518,25 +2518,45 @@ are automatically detected and this attribute 
>>> is i
>>>  @item const
>>>  @cindex @code{const} function attribute
>>>  @cindex functions that have no side effects
>>> -Many functions do not examine any values except their arguments, and
>>> -have no effects except to return a value.  Calls to such functions lend
>>> -themselves to optimization such as common subexpression elimination.
>>> -The presence of the @code{const} attribute on a function declaration 
>>> -allows GCC to emit more efficient code for some calls to the 
>>> function. +Calls to functions whose return value is not affected by 
>>> changes to
>>> +the observable state of the program and that have no observable effects
>>> +on such state other than to return a value may lend themselves to
>>> +optimizations such as common subexpression elimination.  Declaring such
>>> +functions with the @code{const} attribute allows GCC to emit more 
>>> efficient
>>> +code for consecutive calls to the function.
>>
>> I don't think the calls have to be consecutive for GCC to emit more 
>> efficient code.  I'd kill that last bit.
> 
> I added it because I want to make it clear that the attribute
> shouldn't be expected to improve the efficiency of any single
> call.  It can only improve it for the second (and subsequent)
> call with the same argument values as the first.  I've tweaked
> the sentence a bit.
> 
>>
>>> +The @code{const} attribute prohibits a function from reading objects
>>> +that affect its return value between successive invocations.  However,
>>> +functions declared with the attribute can safely read objects that do
>>> +not affect their return value, such as non-volatile constants.
>>>  The @code{const} attribute imposes greater restrictions on a function's
>>> -definition than the similar @code{pure} attribute below because it
>>> -additionally prohibits the function from reading memory except for
>>> -constant global variables.  Decorating the same function with
>>> -both the @code{const} and the @code{pure} attribute is diagnosed.
>>> +definition than the similar @code{pure} attribute.  Declaring the same
>>> +function with both the @code{const} and the @code{pure} attribute is
>>> +diagnosed.  Because a const function cannot have any observable side
>>
>> @code{const}
> 
> I actually meant to bring this up separately.
> 
> I don't think @code would be appropriate in this context.  It's
> not a use of the attribute name but rather a description of
> the function.  Analogous to "a const pointer" or "a volatile
> access" vs "a @code{const}-qualified pointer or
> "the @code{volatile} qualifier."  I think the manual already
> uses this style, albeit not completely consistently.  The C
> and C++ standards aren't 100% consistent either, but I believe
> the editors follow this principle when they think of it.  Unless
> you really do think GCC should go the other way around I would
> like to add this to the GCC style guidelines and fix
> the inconsistencies.
> 
> I thought I was consistent in this in my own changes but I see
> I was not.  I've changed the @code{const} to just const according
> to the above.
> 
>>> +effects it does not make sense for it to return @code{void}.  Declaring
>>> +such a function is diagnosed.
>>>
>>> +For example,
>>> +
>>> +@smallexample
>>> +int square (int) __attribute__ ((const));
>>> +@end smallexample
>>> +
>>> +@noindent
>>> +tells GCC that subsequent calls to function @code{square} with the same
>>> +argument value can be replaced by the result of the first call 
>>> regardless
>>> +of the statements in between.
>>> +
>>
>> I think it would be better to move this example immediately after the 
>> first paragraph, before you digress about the diagnostics and such like.
> 
> Done.
> 
>>
>>>  @cindex pointer arguments
>>>  Note that a function that has pointer arguments and examines the data
>>> -pointed to must @emph{not} be declared @code{const}.  Likewise, a
>>> -function that calls a non-@code{const} function usually must not be
>>> -@code{const}.  Because a @code{const} function cannot have any side
>>> -effects it does not make sense for such a function to return 
>>> @code{void}.
>>> -Declaring such a function is diagnosed.
>>> +pointed to must @emph{not} be declared @code{const} if the pointed-to
>>> +data might change between successive invocations of the function.  In
>>> +general, since a function cannot distinguish data that might change
>>> +from data that cannot, @code{const} functions should never be
>>> +pass-by-reference.  Likewise, a function that calls a non-@code{const}
>>
>> I don't understand what a pass-by-reference function might be.  Do you 
>> mean it should not have reference parameters in C++?
> 
> Yes.  I've clarified it a bit.
> 
>>
>>> +function usually must not be @code{const}.  Because a @code{const}
>>> +function cannot have any side effects it does not make sense for such
>>> +a function to return @code{void}. Declaring such a function is 
>>> diagnosed.
>>
>> The last two sentences duplicate what you say a couple paragraphs 
>> earlier.  We only need to say this once.  :-)
> 
> Ah, right, thank you.
> 
>>
>>>
>>>  @item constructor
>>>  @itemx destructor
>>> @@ -3301,34 +3321,51 @@ to prevent recursion.
>>>  @item pure
>>>  @cindex @code{pure} function attribute
>>>  @cindex functions that have no side effects
>>> -Many functions have no effects except the return value and their
>>> -return value depends only on the parameters and/or global variables.
>>> -Calls to such functions can be subject
>>> -to common subexpression elimination and loop optimization just as an
>>> -arithmetic operator would be.  These functions should be declared
>>> -with the attribute @code{pure}.  For example,
>>>
>>> +Calls to functions that have no observable effects on the state of
>>> +the program other than to return a value may lend themselves to 
>>> optimizations
>>> +such as common subexpression elimination.  Declaring such functions 
>>> with
>>> +the @code{pure} attribute allows GCC to emit more efficient code for
>>> +consecutive calls to the function.
>>
>> Same complaint about "consecutive" as above.
> 
> I've adjusted this sentence as well.
> 
>>
>>> +
>>> +The @code{pure} attribute prohibits a function from modifying the state
>>> +of the program that is observable by means other than inspecting
>>> +the function's return value.  However, functions declared with the 
>>> @code{pure}
>>> +attribute can safely read any non-volatile objects, and modify the 
>>> value of
>>> +objects in a way that does not affect their return value or the 
>>> observable
>>> +state of the program.  Declaring the same function with both the 
>>> @code{const}
>>> +and the @code{pure} attribute is diagnosed.
>>> +
>>> +For example,
>>> +
>>>  @smallexample
>>> -int square (int) __attribute__ ((pure));
>>> +int hash (char *) __attribute__ ((pure));
>>>  @end smallexample
>>>
>>>  @noindent
>>> -says that the hypothetical function @code{square} is safe to call
>>> -fewer times than the program says.
>>> +tells GCC that subsequent calls to the function @code{hash} with the 
>>> same
>>> +string can be replaced by the result of the first call provided the 
>>> state
>>> +of the program observable by @code{hash}, including the contents of 
>>> the array
>>> +itself, does not change in between.  Even though @code{hash} takes a 
>>> non-const
>>
>> non-@code{const}
>>
>>> +pointer argument it must not modify the array it points to, or any 
>>> other object
>>> +whose value the rest of the program may depend on.  However, making 
>>> changes to
>>> +the array between successive calls to the function is permitted.  
>>> The restriction
>>
>> That "making changes" language is confusing.  Can we put that sentence 
>> in a more active voice, like "Other parts of the program can make 
>> changes to the array."?
> 
> Adjusted.
> 
>>
>>> +also applies to member objects referenced by the @code{this} pointer 
>>> in C++
>>> +non-static member functions.
>>>
>>>  Some common examples of pure functions are @code{strlen} or 
>>> @code{memcmp}.
>>>  Interesting non-pure functions are functions with infinite loops or 
>>> those
>>>  depending on volatile memory or other system resource, that may 
>>> change between
>>> -two consecutive calls (such as @code{feof} in a multithreading 
>>> environment).
>>> +consecutive calls (such as the @code{feof} function in a multithreading
>>> +environment).
>>>
>>>  The @code{pure} attribute imposes similar but looser restrictions on
>>>  a function's definition than the @code{const} attribute: @code{pure}
>>> -allows the function to read any non-volatile memory, not just
>>> -constant global variables.  Decorating the same function with
>>> -both the @code{pure} and the @code{const} attribute is diagnosed.
>>> -Because a @code{pure} function cannot have any side effects it does not
>>> -make sense for such a function to return @code{void}.  Declaring such
>>> -a function is diagnosed.
>>> +allows the function to read any non-volatile memory.  Declaring
>>> +the same function with both the @code{pure} and the @code{const} 
>>> attribute
>>> +is diagnosed.  Because a pure function cannot have any observable 
>>> side effects
>>> +it does not make sense for such a function to return @code{void}. 
>>> Declaring
>>> +such a function is diagnosed.
>>
>> Again, those last two sentences duplicate what you already said a 
>> couple paragraphs up.
> 
> Fixed.
> 
> Martin

On 12/13/18 3:52 PM, Martin Sebor wrote:
> Ping: https://gcc.gnu.org/ml/gcc-patches/2018-12/msg00426.html
> 
> (I have now committed the @code{const} cleanup mentioned below.)

This patch is OK except for one nit.

>  @cindex pointer arguments
>  Note that a function that has pointer arguments and examines the data
> -pointed to must @emph{not} be declared @code{const}.  Likewise, a
> -function that calls a non-@code{const} function usually must not be
> -@code{const}.  Because a @code{const} function cannot have any side
> -effects it does not make sense for such a function to return @code{void}.
> -Declaring such a function is diagnosed.
> +pointed to must @emph{not} be declared @code{const} if the pointed-to
> +data might change between successive invocations of the function.  In
> +general, since a function cannot distinguish data that might change
> +from data that cannot, const functions should never be
> +pass-by-reference (take pointer or, in C++, reference arguments).

I'd really rather avoid "pass-by-reference" since it adds nothing with 
the clarification about what it means there, too.  How about just:

...const functions should never take pointer or, in C++, reference 
arguments.

OK to commit with that fixed.

-Sandra

On 12/13/18 7:07 PM, Sandra Loosemore wrote:
> On 12/13/18 3:52 PM, Martin Sebor wrote:
>> Ping: https://gcc.gnu.org/ml/gcc-patches/2018-12/msg00426.html
>>
>> (I have now committed the @code{const} cleanup mentioned below.)
> 
> This patch is OK except for one nit.
> 
>>  @cindex pointer arguments
>>  Note that a function that has pointer arguments and examines the data
>> -pointed to must @emph{not} be declared @code{const}.  Likewise, a
>> -function that calls a non-@code{const} function usually must not be
>> -@code{const}.  Because a @code{const} function cannot have any side
>> -effects it does not make sense for such a function to return 
>> @code{void}.
>> -Declaring such a function is diagnosed.
>> +pointed to must @emph{not} be declared @code{const} if the pointed-to
>> +data might change between successive invocations of the function.  In
>> +general, since a function cannot distinguish data that might change
>> +from data that cannot, const functions should never be
>> +pass-by-reference (take pointer or, in C++, reference arguments).
> 
> I'd really rather avoid "pass-by-reference" since it adds nothing with 
> the clarification about what it means there, too.  How about just:
> 
> ...const functions should never take pointer or, in C++, reference 
> arguments.
> 
> OK to commit with that fixed.

Committed in r267156.

Martin