Update SSA iterator documentation

This reflects the change to drop FOR_EACH_IMM_USE_SAFE and adding
the DTOR to the FOR_EACH_IMM_USE_STMT iterator that cleans up
after an early break.

	* doc/tree-ssa.texi: Remove outdated info on FOR_EACH_IMM_USE_STMT
	iteration, clarify SSA operand parts.
	* ssa-iterators.h: Update toplevel comment.

diff --git a/gcc/doc/tree-ssa.texi b/gcc/doc/tree-ssa.texi
index dc6a111701e6c16700665aaaa77e04e3d0459804..25aa006d48ebaebebd897a845fa4257f31fa4c6f 100644 (file)
--- a/gcc/doc/tree-ssa.texi
+++ b/gcc/doc/tree-ssa.texi
@@ -355,7 +355,7 @@ FOR_EACH_PHI_OR_STMT_DEF (def_operand_p, phi, iter, flags)
 
 Immediate use information is now always available.  Using the immediate use
 iterators, you may examine every use of any @code{SSA_NAME}. For instance,
-to change each use of @code{ssa_var} to @code{ssa_var2} and call fold_stmt on
+to change each use of @code{ssa_var} to @code{val} and call fold_stmt on
 each stmt after that is done:
 
 @smallexample
@@ -367,8 +367,9 @@ each stmt after that is done:
   FOR_EACH_IMM_USE_STMT (stmt, iterator, ssa_var)
     @{
       FOR_EACH_IMM_USE_ON_STMT (imm_use_p, iterator)
-        SET_USE (imm_use_p, ssa_var_2);
+        SET_USE (imm_use_p, val);
       fold_stmt (stmt);
+      update_stmt (stmt);
     @}
 @end smallexample
 
@@ -389,9 +390,7 @@ terminated early; a destructor takes care of that when leaving the
 @code{FOR_EACH_IMM_USE_STMT} scope.
 
 There are checks in @code{verify_ssa} which verify that the immediate use list
-is up to date, as well as checking that an optimization didn't break from the
-loop without using this macro.  It is safe to simply 'break'; from a
-@code{FOR_EACH_IMM_USE_FAST} traverse.
+is up to date.
 
 Some useful functions and macros:
 @enumerate
@@ -412,7 +411,9 @@ isn't located in a @code{PHI} node.
 @end enumerate
 
 Note that uses are not put into an immediate use list until their statement is
-actually inserted into the instruction stream via a @code{bsi_*} routine.
+actually inserted into the instruction stream via a @code{gsi_*} routine
+which calls @code{update_stmt} to re-scan SSA operands and update the
+immediate use lists.
 
 It is also still possible to utilize lazy updating of statements, but this
 should be used only when absolutely required.  Both alias analysis and the

diff --git a/gcc/ssa-iterators.h b/gcc/ssa-iterators.h
index 03d701c8ba5c86b589674c4a8cccd438ca902e34..0822a98323d82586dbcb8f813f2e5f94c15d72ed 100644 (file)
--- a/gcc/ssa-iterators.h
+++ b/gcc/ssa-iterators.h
@@ -36,25 +36,17 @@ along with GCC; see the file COPYING3.  If not see
    base for a circular list, and initially this is the only node in
    the list.
 
-   Fast iteration allows each use to be examined, but does not allow
-   any modifications to the uses or stmts.
-
-   Normal iteration allows insertion, deletion, and modification. the
-   iterator manages this by inserting a marker node into the list
-   immediately before the node currently being examined in the list.
-   this marker node is uniquely identified by having null stmt *and* a
-   null use pointer.
-
-   When iterating to the next use, the iteration routines check to see
-   if the node after the marker has changed. if it has, then the node
-   following the marker is now the next one to be visited. if not, the
-   marker node is moved past that node in the list (visualize it as
-   bumping the marker node through the list).  this continues until
-   the marker node is moved to the original anchor position. the
-   marker node is then removed from the list.
-
-   If iteration is halted early, the marker node must be removed from
-   the list before continuing.  */
+   Fast iteration via FOR_EACH_IMM_USE_FAST allows each use to be
+   examined, but does not allow any modifications to the uses or stmts.
+
+   Safe iteration via FOR_EACH_IMM_USE_STMT and FOR_EACH_IMM_USE_ON_STMT
+   allows insertion, deletion, and modification of SSA operands within
+   the current stmt iterated.  The iterator manages this by re-sorting
+   the immediate uses to batch uses on a single stmt after each other
+   and inserts a marker node into the list immediately after the node
+   ending the current batch.  This marker node is uniquely identified by
+   having null stmt *and* a null use pointer.  */
+
 struct imm_use_iterator
 {
   /* This is the current use the iterator is processing.  */