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

[Matthias Springer]

https://github.com/matthias-springer created https://github.com/llvm/llvm-project/pull/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`.


>From d81a62a8b9ca61b9593288d8b01230f355cc3235 Mon Sep 17 00:00:00 2001
From: Matthias Springer <me at m-sp.org>
Date: Sat, 6 Jun 2026 09:04:49 +0000
Subject: [PATCH] [mlir][Interfaces] Document completeness requirement of
 `RegionBranchOpInterface`

---
 .../mlir/Interfaces/ControlFlowInterfaces.td     | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td b/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
index 06fa724e05fab..3de8de9b5c760 100644
--- a/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
+++ b/mlir/include/mlir/Interfaces/ControlFlowInterfaces.td
@@ -118,15 +118,23 @@ 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:
+    Completeness is a core contract of this interface: the implementation must
+    model all possible control flow edges, so that callers can rely on the
+    returned information as a complete picture. Failing to report a possible
+    edge is an incorrect implementation and may cause analyses/transformations
+    to produce incorrect results. (It is acceptable to over-approximate by
+    reporting edges that turn out to be infeasible at runtime.)
+
+    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