diff mbox

[wwwdocs] Update Fortran secrion in 4.8/changes.html

Message ID alpine.LNX.2.00.1211190719110.2085@tuna.site
State New
Headers show

Commit Message

Gerald Pfeifer Nov. 19, 2012, 3:40 p.m. UTC 
On Mon, 12 Nov 2012, Tobias Burnus wrote:
> Well, "flag" is GCC teminology (see "man gcc"), though it seems to be 
> only used for the -f* options while I (mis)used it here for -W*. I
> think it is better to use the more common term "command-line option".

Okay, so I went ahead and applied the patch below.

There is one sentence (preceding my patch) which I don't quite 
understand (specifically around the "to"):

  "...which diagnose when code to is inserted for automatic
  (re)allocation of a variable during assignment."

Gerald

Comments

Tobias Burnus Nov. 19, 2012, 4:21 p.m. UTC | #1 
Gerald Pfeifer wrote:
> There is one sentence (preceding my patch) which I don't quite
> understand (specifically around the "to"):
>
>    "...which diagnose when code to is inserted for automatic
>    (re)allocation of a variable during assignment."

Let me try to explain what the warning does and what "automatic 
(re)allocation" is; either the meaning becomes clear – or you might get 
an idea how to improve the wording.

But I concur that the current version is odd; it should either be "when 
code is [or: "will be"] inserted" or, maybe, "when code is to be inserted".

* * *

Fortran has allocatable variables, e.g.
real, allocatable :: array(:)

If one now has the assignment
array = [ 1, 2, 3, 4 ]
the "array" gets automatically allocated for an array size of 4 before 
the assignment. If one now has
array = [ 5,6,7,8 ]
there is only the assignment as "array" is already allocated while for
array = [ 1, 2 ]
"array" is reallocated to have an array size of 2 (and then the array 
"[1,2]" is assigned).

In order to do this, the compiler has to add a check whether the LHS is 
allocated and whether the type parameters (e.g. the [allocatable] string 
length) and array shape are the same. Thus, the compiler adds internally 
a lot of code.

While this (re)allocate-on-assignment feature is very convenient, it can 
cause some severe slow down if it occurs in a hot loop. If users knows 
that the variable is allocated and of the correct shape (should be true 
for all code before Fortran 2003), they can either disable the feature 
(-std=f95, -fno-realloc-lhs) or they can prevent the reallocation by 
using a (whole) array section, e.g. "array(:) = [5,6,7,8]". And to avoid 
guessing where reallocation on assignment might happen, the warning 
shows where. Thus, the warning helps with performance tuning.

Tobias
diff mbox

Patch

Index: changes.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/gcc-4.8/changes.html,v
retrieving revision 1.56
diff -u -3 -p -r1.56 changes.html
--- changes.html	12 Nov 2012 15:19:33 -0000	1.56
+++ changes.html	19 Nov 2012 15:19:03 -0000
@@ -169,20 +169,20 @@  B b(42); // OK
   <ul>
     <li>The <code><a
     href="http://gcc.gnu.org/onlinedocs/gfortran/Error-and-Warning-Options.html">
-    -Wc-binding-type</a></code> warning flag has been added (by default
-    disabled), which warns if the a variable might not be C interoperable. In
+    -Wc-binding-type</a></code> warning option has been added (disabled
+    by default), which warns if the a variable might not be C interoperable. In
     particular, if the variable has been declared using an intrinsic type with
     default kind instead of using a kind parameter defined for C
     interoperability in the intrinsic <code>ISO_C_Binding</code> module. Before,
-    the warning was always printed. The <code>-Wc-binding-type</code> flag
+    the warning was always printed. The <code>-Wc-binding-type</code> option
     is enabled by <code>-Wall</code>.</li>
 
     <li>The <a
     href="http://gcc.gnu.org/onlinedocs/gfortran/Error-and-Warning-Options.html">
     <code>-Wrealloc-lhs</code></a> and <code>-Wrealloc-lhs-all</code> warning
-    flags have been added, which diagnose when code to is inserted for automatic
-    (re)allocation of a variable during assignment. The flag can be used to
-    decide whether it is safe to use <code><a
+    command-line options have been added, which diagnose when code to is
+    inserted for automatic (re)allocation of a variable during assignment.
+    This option can be used to decide whether it is safe to use <code><a
     href="http://gcc.gnu.org/onlinedocs/gfortran/Code-Gen-Options.html">
     -fno-realloc-lhs</a></code>. Additionally, it can be used to find automatic
     (re)allocation in hot loops. (For arrays, replacing <q><code>var=</code></q>
@@ -190,8 +190,8 @@  B b(42); // OK
 
     <li>The <a
     href="http://gcc.gnu.org/onlinedocs/gfortran/Error-and-Warning-Options.html">
-    <code>-Wcompare-reals</code></a> flag has been added. When this flag is set,
-    warnings are issued when comparing <code>REAL</code> or
+    <code>-Wcompare-reals</code></a> command-line option has been added. When
+    this is set, warnings are issued when comparing <code>REAL</code> or
     <code>COMPLEX</code> types for equality and inequality; consider replacing
     <code>a == b</code> by <code>abs(a&minus;b) &lt; eps</code> with a suitable
     <code>eps</code>. <code>-Wcompare-reals</code> is enabled by
@@ -199,9 +199,9 @@  B b(42); // OK
 
     <li>The <a
     href="http://gcc.gnu.org/onlinedocs/gfortran/Error-and-Warning-Options.html">
-    <code>-Wtarget-lifetime</code></a> flag has been added (enabled with
-    <code>-Wall</code>), which warns if the pointer in a pointer assignment
-    might outlive its target.</li>
+    <code>-Wtarget-lifetime</code></a> command-line option has been added
+    (enabled with <code>-Wall</code>), which warns if the pointer in a
+    pointer assignment might outlive its target.</li>
 
     <li><p>Reading floating point numbers which use <q><code>q</code></q> for
     the exponential (such as <code>4.0q0</code>) is now supported as vendor