[Mlir-commits] [mlir] 944284f - [mlir][Interfaces] Document completeness requirement of `RegionBranchOpInterface` (#202018)

[llvmlistbot at llvm.org]

Author: Matthias Springer
Date: 2026-06-09T12:01:56+02:00
New Revision: 944284fe6329eb133bdbf9af77af6fa0cd280070

URL: https://github.com/llvm/llvm-project/commit/944284fe6329eb133bdbf9af77af6fa0cd280070
DIFF: https://github.com/llvm/llvm-project/commit/944284fe6329eb133bdbf9af77af6fa0cd280070.diff

LOG: [mlir][Interfaces] Document completeness requirement of `RegionBranchOpInterface` (#202018)

Document that interface implementations must report all possible control
flow edges. Failure to report a possible edge may break
analyses/transformations/APIs such as
`RegionBranchOpInterface::isRepetitiveRegion`.

Added: 
    

Modified: 
    mlir/include/mlir/Interfaces/ControlFlowInterfaces.td

Removed: 
    


################################################################################
diff  --git a/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td b/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
index 06fa724e05fab..a4c5cd4a8d5a2 100644
--- a/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
+++ b/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
@@ -118,15 +118,16 @@ def BranchOpInterface : OpInterface<"BranchOpInterface"> {
 def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
   let description = [{
     This interface provides information for region-holding operations that
-    exhibit branching behavior between held regions. I.e., this interface allows
-    for expressing control flow information for region holding operations.
+    exhibit branching behavior between held regions. It models the control flow
+    edges between regions (and between the op and its regions), as well as the
+    data flow (value propagation) that occurs along those control flow edges.
 
     This interface is meant to model well-defined cases of control-flow and
     value propagation, where what occurs along control-flow edges is assumed to
     be side-effect free.
 
-    A "region branch point" indicates a point from which a branch originates. It
-    can indicate:
+    A "region branch point" indicates the point from which a branch (edge)
+    originates. It can indicate:
     1. A `RegionBranchTerminatorOpInterface` terminator in any of the
        immediately nested regions of this op.
     2. `RegionBranchPoint::parent()`: the branch originates from outside of the
@@ -198,14 +199,13 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
       }]
     >,
     InterfaceMethod<[{
-        Returns the potential region successors when first executing the op.
+        Returns all potential region successors when first executing the op.
 
-        Unlike `getSuccessorRegions`, this method also passes along the
-        constant operands of this op. Based on these, the implementation may
-        filter out certain successors. By default, simply dispatches to
-        `getSuccessorRegions`. `operands` contains an entry for every
-        operand of this op, with a null attribute if the operand has no constant
-        value.
+        Unlike `getSuccessorRegions`, this method also receives the constant
+        operands of this op (one entry per operand, "null" if the operand has
+        no/unknown constant value). The implementation may use this information
+        to filter out successors. By default, it simply dispatches to
+        `getSuccessorRegions`.
 
         Note: The control flow does not necessarily have to enter any region of
         this op.
@@ -245,7 +245,7 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
            "::llvm::SmallVectorImpl<::mlir::RegionSuccessor> &":$regions)
     >,
     InterfaceMethod<[{
-        Returns the potential region successors when branching from any
+        Returns all potential region successors when branching from any
         terminator in `region`.
       }],
       "void", "getSuccessorRegions",
@@ -276,7 +276,7 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
         return ::mlir::ValueRange();
       }]>,
     InterfaceMethod<[{
-        Returns the potential branching points (predecessors) for a given
+        Returns all potential branching points (predecessors) for a given
         region successor.
       }],
       "void", "getPredecessors",
@@ -297,7 +297,7 @@ def RegionBranchOpInterface : OpInterface<"RegionBranchOpInterface"> {
         }
       }]>,
     InterfaceMethod<[{
-        Returns the potential values across all (predecessors) for a given successor
+        Returns all potential values across all (predecessors) for a given successor
         input, modeled by its index (its position in the list of values).
       }],
       "void", "getPredecessorValues",
@@ -439,14 +439,13 @@ def RegionBranchTerminatorOpInterface :
       }]
     >,
     InterfaceMethod<[{
-        Returns the potential region successors that are branched to after this
+        Returns all potential region successors that are branched to after this
         terminator based on the given constant operands.
 
-        This method also passes along the constant operands of this op.
-        `operands` contains an entry for every operand of this op, with a null
-        attribute if the operand has no constant value.
-
-        The default implementation simply dispatches to the parent
+        This method also receives the constant operands of this op (one entry
+        per operand, "null" if the operand has no/unknown constant value). The
+        implementation may use this information to filter out successors.
+        By default, it simply dispatches to the parent
         `RegionBranchOpInterface`'s `getSuccessorRegions` implementation.
       }],
       "void", "getSuccessorRegions",