https://gcc.gnu.org/g:36c44c2d66664043ecfe0452bb34dff3b9994d70
commit r16-5055-g36c44c2d66664043ecfe0452bb34dff3b9994d70 Author: Richard Biener <[email protected]> Date: Wed Nov 5 09:57:34 2025 +0100 Update immediate use iterator documentation This clarifies the constraints of the immediate use iterators, documenting how exactly stmts and their immediate uses might be altered during it. * doc/tree-ssa.texi: Update immediate use iterator documentation. * ssa-iterators.h: Likewise. Diff: --- gcc/doc/tree-ssa.texi | 33 ++++++++++++++++++++++++++++----- gcc/ssa-iterators.h | 8 ++++---- 2 files changed, 32 insertions(+), 9 deletions(-) diff --git a/gcc/doc/tree-ssa.texi b/gcc/doc/tree-ssa.texi index 25aa006d48eb..670571e1cb09 100644 --- a/gcc/doc/tree-ssa.texi +++ b/gcc/doc/tree-ssa.texi @@ -383,11 +383,34 @@ under the iterators, so use the @code{FOR_EACH_IMM_USE_STMT} and sanity of the use list by moving all the uses for a statement into a controlled position, and then iterating over those uses. Then the optimization can manipulate the stmt when all the uses have been -processed. This is a little slower than the FAST version since it adds a -placeholder element and must sort through the list a bit for each statement. -This placeholder element must be also be removed if the loop is -terminated early; a destructor takes care of that when leaving the -@code{FOR_EACH_IMM_USE_STMT} scope. +processed. Only the current active @code{imm_use_p} may be altered +when using an inner @code{FOR_EACH_IMM_USE_ON_STMT} iteration. +You have to be careful to not inadvertedly modify the immediate +use list by working on another stmt than the the current @code{stmt} during +the iteration. In particular calling @code{update_stmt} is destructive +on all SSA uses immediate use lists related to the updated stmt. +This slower than the FAST version since it sorts through the list for each +statement. + +@code{FOR_EACH_IMM_USE_ON_STMT} iteration may not be nested inside +another @code{FOR_EACH_IMM_USE_ON_STMT} or @code{FOR_EACH_IMM_USE_FAST} +iteration of the same immediate use list. + +There is the @code{gather_imm_use_stmts} helper that trades memory for +removing the need to care about the immediate use list consistency and +which also avoids duplicate visiting of stmts that can occur with +@code{FOR_EACH_IMM_USE_FAST} when there are multiple uses of an SSA name +on a stmt. This can be used to iterate safely over all use stmts like +this: + +@smallexample + tree ssa_var; + + for (gimple *use_stmt : gather_imm_use_stmts (ssa_var)) + @{ + // do something with use_stmt + @} +@end smallexample There are checks in @code{verify_ssa} which verify that the immediate use list is up to date. diff --git a/gcc/ssa-iterators.h b/gcc/ssa-iterators.h index d6bd15c8ade7..47220c5ce25a 100644 --- a/gcc/ssa-iterators.h +++ b/gcc/ssa-iterators.h @@ -42,10 +42,10 @@ along with GCC; see the file COPYING3. If not see 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. */ + the immediate uses to batch uses on a single stmt after each other. + If using an inner FOR_EACH_IMM_USE_ON_STMT iteration only the active + use may be manipulated. Safety relies on new immediate uses being + inserted at the front of immediate use lists. */ struct imm_use_iterator {
