From d3159cce459d40a8f2ac5d86b059536f73a12425 Mon Sep 17 00:00:00 2001 From: Richard Biener Date: Fri, 31 Oct 2025 14:15:25 +0100 Subject: [PATCH] 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. --- gcc/doc/tree-ssa.texi | 13 +++++++------ gcc/ssa-iterators.h | 30 +++++++++++------------------- 2 files changed, 18 insertions(+), 25 deletions(-) diff --git a/gcc/doc/tree-ssa.texi b/gcc/doc/tree-ssa.texi index dc6a111701e6..25aa006d48eb 100644 --- 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 03d701c8ba5c..0822a98323d8 100644 --- 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. */ -- 2.47.3