gcc/doc/gccint/analysis-and-representation-of-loops/loop-querying.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: Loop querying
   7
   8 .. _loop-querying:
   9
  10 Loop querying
  11 *************
  12
  13 The functions to query the information about loops are declared in
  14 :samp:`cfgloop.h`.  Some of the information can be taken directly from
  15 the structures.  ``loop_father`` field of each basic block contains
  16 the innermost loop to that the block belongs.  The most useful fields of
  17 loop structure (that are kept up-to-date at all times) are:
  18
  19 * ``header``, ``latch`` : Header and latch basic blocks of the
  20   loop.
  21
  22 * ``num_nodes`` : Number of basic blocks in the loop (including
  23   the basic blocks of the sub-loops).
  24
  25 * ``outer``, ``inner``, ``next`` : The super-loop, the first
  26   sub-loop, and the sibling of the loop in the loops tree.
  27
  28 There are other fields in the loop structures, many of them used only by
  29 some of the passes, or not updated during CFG changes; in general, they
  30 should not be accessed directly.
  31
  32 The most important functions to query loop structures are:
  33
  34 * ``loop_depth`` : The depth of the loop in the loops tree, i.e., the
  35   number of super-loops of the loop.
  36
  37 * ``flow_loops_dump`` : Dumps the information about loops to a
  38   file.
  39
  40 * ``verify_loop_structure`` : Checks consistency of the loop
  41   structures.
  42
  43 * ``loop_latch_edge`` : Returns the latch edge of a loop.
  44
  45 * ``loop_preheader_edge`` : If loops have preheaders, returns
  46   the preheader edge of a loop.
  47
  48 * ``flow_loop_nested_p`` : Tests whether loop is a sub-loop of
  49   another loop.
  50
  51 * ``flow_bb_inside_loop_p`` : Tests whether a basic block belongs
  52   to a loop (including its sub-loops).
  53
  54 * ``find_common_loop`` : Finds the common super-loop of two loops.
  55
  56 * ``superloop_at_depth`` : Returns the super-loop of a loop with
  57   the given depth.
  58
  59 * ``tree_num_loop_insns``, ``num_loop_insns`` : Estimates the
  60   number of insns in the loop, on GIMPLE and on RTL.
  61
  62 * ``loop_exit_edge_p`` : Tests whether edge is an exit from a
  63   loop.
  64
  65 * ``mark_loop_exit_edges`` : Marks all exit edges of all loops
  66   with ``EDGE_LOOP_EXIT`` flag.
  67
  68 * ``get_loop_body``, ``get_loop_body_in_dom_order``,
  69   ``get_loop_body_in_bfs_order`` : Enumerates the basic blocks in the
  70   loop in depth-first search order in reversed CFG, ordered by dominance
  71   relation, and breath-first search order, respectively.
  72
  73 * ``single_exit`` : Returns the single exit edge of the loop, or
  74   ``NULL`` if the loop has more than one exit.  You can only use this
  75   function if ``LOOPS_HAVE_RECORDED_EXITS`` is used.
  76
  77 * ``get_loop_exit_edges`` : Enumerates the exit edges of a loop.
  78
  79 * ``just_once_each_iteration_p`` : Returns true if the basic block
  80   is executed exactly once during each iteration of a loop (that is, it
  81   does not belong to a sub-loop, and it dominates the latch of the loop).