[patch][DOC]PR97309--improve documentation of -fallow-store-data-races

[patch][DOC]PR97309--improve documentation of -fallow-store-data-races

[Qing Zhao]

Richard,

On behalf of John Henning, I am sending the following simple documentation patch 
for an official approval.  Hopefully this patch can get into gcc11.

Per John, the wording of the documentation change was based on the discussion
 between him and you on 25-Aug-2020. 

I created a gcc bugzilla bug https://gcc.gnu.org/bugzilla/show_bug.cgi?id=97309
to record this issue. 

Okay to commit?

thanks.

Qing

ChangeLog:


2020-10-06  John Henning  <john.henning@oracle.com>

	* gcc/doc/invoke.texi: Improve documentation of -fallow-store-data-races

---
 gcc/doc/invoke.texi | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 7c81d7f41bd..926ee1ff28e 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -11621,7 +11621,18 @@ Do not remove unused C++ allocations in dead code elimination.
 
 @item -fallow-store-data-races
 @opindex fallow-store-data-races
-Allow the compiler to introduce new data races on stores.
+Allow the compiler to perform optimizations that may introduce new data races
+on stores, without proving that the variable cannot be concurrently accessed
+by other threads.  Does not affect optimization of local data.  It is safe to
+use this option if it is known that global data will not be accessed by 
+multiple threads. 
+ 
+Examples of optimizations enabled by @option{-fallow-store-data-races} include
+hoisting or if-conversions that may cause a value that was already in memory 
+to be re-written with that same value.  Such re-writing is safe in a single 
+threaded context but may be unsafe in a multi-threaded context.  Note that on
+some processors, if-conversions may be required in order to enable 
+vectorization. 
 
 Enabled at level @option{-Ofast}.
 
-- 
2.11.0

Re: [patch][DOC]PR97309--improve documentation of -fallow-store-data-races

[Richard Biener]

On Tue, 6 Oct 2020, Qing Zhao wrote:

> Richard,
> 
> On behalf of John Henning, I am sending the following simple documentation patch 
> for an official approval.  Hopefully this patch can get into gcc11.
> 
> Per John, the wording of the documentation change was based on the discussion
>  between him and you on 25-Aug-2020. 
> 
> I created a gcc bugzilla bug https://gcc.gnu.org/bugzilla/show_bug.cgi?id=97309
> to record this issue. 
> 
> Okay to commit?

OK.

Richard.

> thanks.
> 
> Qing
> 
> ChangeLog:
> 
> 
> 2020-10-06  John Henning  <john.henning@oracle.com>
> 
> 	* gcc/doc/invoke.texi: Improve documentation of -fallow-store-data-races
> 
> ---
>  gcc/doc/invoke.texi | 13 ++++++++++++-
>  1 file changed, 12 insertions(+), 1 deletion(-)
> 
> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index 7c81d7f41bd..926ee1ff28e 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -11621,7 +11621,18 @@ Do not remove unused C++ allocations in dead code elimination.
>  
>  @item -fallow-store-data-races
>  @opindex fallow-store-data-races
> -Allow the compiler to introduce new data races on stores.
> +Allow the compiler to perform optimizations that may introduce new data races
> +on stores, without proving that the variable cannot be concurrently accessed
> +by other threads.  Does not affect optimization of local data.  It is safe to
> +use this option if it is known that global data will not be accessed by 
> +multiple threads. 
> + 
> +Examples of optimizations enabled by @option{-fallow-store-data-races} include
> +hoisting or if-conversions that may cause a value that was already in memory 
> +to be re-written with that same value.  Such re-writing is safe in a single 
> +threaded context but may be unsafe in a multi-threaded context.  Note that on
> +some processors, if-conversions may be required in order to enable 
> +vectorization. 
>  
>  Enabled at level @option{-Ofast}.
>  
> 

-- 
Richard Biener <rguenther@suse.de>
SUSE Software Solutions Germany GmbH, Maxfeldstrasse 5, 90409 Nuernberg,
Germany; GF: Felix Imend