[mlir][IR] Deprecate match and rewrite functions (#130031)

Deprecate the `match` and `rewrite` functions. They mainly exist for
historic reasons. This PR also updates all remaining uses of in the MLIR
codebase.

This is addressing a
[comment](#129861 (review))
on an earlier PR.

Note for LLVM integration: `SplitMatchAndRewrite` will be deleted soon,
update your patterns to use `matchAndRewrite` instead of separate
`match` / `rewrite`.

---------

Co-authored-by: Jakub Kuderski <[email protected]>

Author: matthias-springer

mlir/docs/DialectConversion.md

@@ -179,13 +179,13 @@ updated/remapped operands of an operation, such as when the types of results
 defined by an operation have changed. The general Rewrite Patterns can no longer
 be used in these situations, as the types of the operands of the operation being
 matched will not correspond with those expected by the user. This pattern
-provides, as an additional argument to the `matchAndRewrite` and `rewrite`
-methods, the list of operands that the operation should use after conversion. If
-an operand was the result of a non-converted operation, for example if it was
-already legal, the original operand is used. This means that the operands
-provided always have a 1-1 non-null correspondence with the operands on the
-operation. The original operands of the operation are still intact and may be
-inspected as normal. These patterns also utilize a special `PatternRewriter`,
+provides, as an additional argument to the `matchAndRewrite` method, the list
+of operands that the operation should use after conversion. If an operand was
+the result of a non-converted operation, for example if it was already legal,
+the original operand is used. This means that the operands provided always have
+a 1-1 non-null correspondence with the operands on the operation. The original
+operands of the operation are still intact and may be inspected as normal.
+These patterns also utilize a special `PatternRewriter`,
 `ConversionPatternRewriter`, that provides special hooks for use with the
 conversion infrastructure.
 

mlir/docs/PatternRewriter.md

@@ -48,13 +48,9 @@ operation type, a special tag must be provided to make the intent explicit:
 ### `matchAndRewrite` implementation
 
 This is the chunk of code that matches a given root `Operation` and performs a
-rewrite of the IR. A `RewritePattern` can specify this implementation either via
-the `matchAndRewrite` method or via separate `match` and `rewrite` methods when
-deriving from `RewritePattern::SplitMatchAndRewrite`. When using the combined
-`matchAndRewrite` method, no IR mutation should take place before the match is
-deemed successful. The combined `matchAndRewrite` is useful when non-trivially
-recomputable information is required by the matching and rewriting phase. See
-below for examples:
+rewrite of the IR. A `RewritePattern` can specify this implementation via the
+`matchAndRewrite` method. No IR mutation should take place before the match is
+deemed successful. See below for examples:
 
 ```c++
 class MyPattern : public RewritePattern {
@@ -67,21 +63,6 @@ public:
   MyPattern(PatternBenefit benefit)
       : RewritePattern(benefit, MatchAnyOpTypeTag()) {}
 
-  /// In this section, the `match` and `rewrite` implementation is specified
-  /// using the separate hooks.
-  LogicalResult match(Operation *op) const override {
-    // The `match` method returns `success()` if the pattern is a match, failure
-    // otherwise.
-    // ...
-  }
-  void rewrite(Operation *op, PatternRewriter &rewriter) const override {
-    // The `rewrite` method performs mutations on the IR rooted at `op` using
-    // the provided rewriter. All mutations must go through the provided
-    // rewriter.
-  }
-
-  /// In this section, the `match` and `rewrite` implementation is specified
-  /// using a single hook.
   LogicalResult matchAndRewrite(Operation *op, PatternRewriter &rewriter) const override {
     // The `matchAndRewrite` method performs both the matching and the mutation.
     // Note that the match must reach a successful point before IR mutation may
@@ -92,12 +73,6 @@ public:
 
 #### Restrictions
 
-Within the `match` section of a pattern, the following constraints apply:
-
-*   No mutation of the IR is allowed.
-
-Within the `rewrite` section of a pattern, the following constraints apply:
-
 *   All IR mutations, including creation, *must* be performed by the given
     `PatternRewriter`. This class provides hooks for performing all of the
     possible mutations that may take place within a pattern. For example, this
@@ -107,8 +82,6 @@ Within the `rewrite` section of a pattern, the following constraints apply:
 *   The root operation is required to either be: updated in-place, replaced, or
     erased.
 *   `matchAndRewrite` must return "success" if and only if the IR was modified.
-    `match` must return "success" if and only if the IR is going to be modified
-    during `rewrite`.
 
 
 ### Application Recursion

mlir/docs/Tutorials/QuickstartRewrites.md

@@ -216,25 +216,6 @@ In case ODS patterns and `matchAndRewrite`-style functions are not sufficient
 you can also specify rewrites as a general set of `RewritePattern`s:
 
 ```c++
-/// Multi-step rewrite using "match" and "rewrite". This allows for separating
-/// the concerns of matching and rewriting.
-struct ConvertTFLeakyRelu : public RewritePattern {
-  ConvertTFLeakyRelu(MLIRContext *context)
-      : RewritePattern("tf.LeakyRelu", 1, context) {}
-
-  LogicalResult match(Operation *op) const override {
-    return success();
-  }
-
-  void rewrite(Operation *op, PatternRewriter &rewriter) const override {
-    rewriter.replaceOpWithNewOp<TFL::LeakyReluOp>(
-        op, op->getResult(0).getType(), op->getOperand(0),
-        /*alpha=*/op->getAttrOfType<FloatAttr>("alpha"));
-  }
-};
-
-/// Single-step rewrite with "matchAndRewrite". This allows for performing the
-/// rewrite immediately upon a successful match.
 struct ConvertTFLeakyRelu : public RewritePattern {
   ConvertTFLeakyRelu(MLIRContext *context)
       : RewritePattern("tf.LeakyRelu", 1, context) {}

mlir/include/mlir/Conversion/LLVMCommon/Pattern.h

@@ -40,6 +40,8 @@ LogicalResult oneToOneRewrite(
 /// during the entire pattern lifetime.
 class ConvertToLLVMPattern : public ConversionPattern {
 public:
+  /// `SplitMatchAndRewrite` is deprecated. Use `matchAndRewrite` instead of
+  /// separate `match` and `rewrite`.
   using SplitMatchAndRewrite =
       detail::ConversionSplitMatchAndRewriteImpl<ConvertToLLVMPattern>;
 
@@ -149,6 +151,9 @@ class ConvertOpToLLVMPattern : public ConvertToLLVMPattern {
   using OpAdaptor = typename SourceOp::Adaptor;
   using OneToNOpAdaptor =
       typename SourceOp::template GenericAdaptor<ArrayRef<ValueRange>>;
+
+  /// `SplitMatchAndRewrite` is deprecated. Use `matchAndRewrite` instead of
+  /// separate `match` and `rewrite`.
   using SplitMatchAndRewrite = detail::ConversionSplitMatchAndRewriteImpl<
       ConvertOpToLLVMPattern<SourceOp>>;
 

mlir/include/mlir/IR/PatternMatch.h

@@ -237,6 +237,9 @@ class Pattern {
 namespace detail {
 /// Helper class that derives from a RewritePattern class and provides separate
 /// `match` and `rewrite` entry points instead of a combined `matchAndRewrite`.
+///
+/// This class is deprecated. Use `matchAndRewrite` instead of separate `match`
+/// and `rewrite`.
 template <typename PatternT>
 class SplitMatchAndRewriteImpl : public PatternT {
   using PatternT::PatternT;
@@ -268,6 +271,9 @@ class SplitMatchAndRewriteImpl : public PatternT {
 class RewritePattern : public Pattern {
 public:
   using OperationT = Operation *;
+
+  /// `SplitMatchAndRewrite` is deprecated. Use `matchAndRewrite` instead of
+  /// separate `match` and `rewrite`.
   using SplitMatchAndRewrite = detail::SplitMatchAndRewriteImpl<RewritePattern>;
 
   virtual ~RewritePattern() = default;
@@ -350,6 +356,9 @@ struct OpOrInterfaceRewritePatternBase : public RewritePattern {
 template <typename SourceOp>
 struct OpRewritePattern
     : public detail::OpOrInterfaceRewritePatternBase<SourceOp> {
+
+  /// `SplitMatchAndRewrite` is deprecated. Use `matchAndRewrite` instead of
+  /// separate `match` and `rewrite`.
   using SplitMatchAndRewrite =
       detail::SplitMatchAndRewriteImpl<OpRewritePattern<SourceOp>>;
 
@@ -368,6 +377,9 @@ struct OpRewritePattern
 template <typename SourceOp>
 struct OpInterfaceRewritePattern
     : public detail::OpOrInterfaceRewritePatternBase<SourceOp> {
+
+  /// `SplitMatchAndRewrite` is deprecated. Use `matchAndRewrite` instead of
+  /// separate `match` and `rewrite`.
   using SplitMatchAndRewrite =
       detail::SplitMatchAndRewriteImpl<OpInterfaceRewritePattern<SourceOp>>;
 

mlir/include/mlir/Transforms/DialectConversion.h

@@ -598,6 +598,9 @@ class ConversionPattern : public RewritePattern {
   using OperationT = Operation *;
   using OpAdaptor = ArrayRef<Value>;
   using OneToNOpAdaptor = ArrayRef<ValueRange>;
+
+  /// `SplitMatchAndRewrite` is deprecated. Use `matchAndRewrite` instead of
+  /// separate `match` and `rewrite`.
   using SplitMatchAndRewrite =
       detail::ConversionSplitMatchAndRewriteImpl<ConversionPattern>;
 
@@ -669,6 +672,9 @@ class OpConversionPattern : public ConversionPattern {
   using OpAdaptor = typename SourceOp::Adaptor;
   using OneToNOpAdaptor =
       typename SourceOp::template GenericAdaptor<ArrayRef<ValueRange>>;
+
+  /// `SplitMatchAndRewrite` is deprecated. Use `matchAndRewrite` instead of
+  /// separate `match` and `rewrite`.
   using SplitMatchAndRewrite =
       detail::ConversionSplitMatchAndRewriteImpl<OpConversionPattern<SourceOp>>;