Add flags for annotating Generic{,1} methods INLINE[1] (#11068)

Makes it possible for GHC to optimize away intermediate Generic representation
for more types.

Metric Increase:
    T12227

2 files changed, 50 insertions, 0 deletions

diff --git a/docs/users_guide/9.2.1-notes.rst b/docs/users_guide/9.2.1-notes.rst
index 673fc9f169..b691fc0537 100644
--- a/docs/users_guide/9.2.1-notes.rst
+++ b/docs/users_guide/9.2.1-notes.rst
@@ -28,6 +28,12 @@ Compiler
   since the argument was already forced in the first equation. For more
   details see :ghc-flag:`-Wredundant-bang-patterns`.
 
+- New ``-finline-generics`` and ``-finline-generics-aggressively`` flags for
+  improving performance of generics-based algorithms.
+
+  For more details see :ghc-flag:`-finline-generics` and
+  :ghc-flag:`-finline-generics-aggressively`.
+
 - Type checker plugins which work with the natural numbers now
   should use ``naturalTy`` kind instead of ``typeNatKind``, which has been removed.
 
diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst
index c278e6903d..b54e7e3e2e 100644
--- a/docs/users_guide/using-optimisation.rst
+++ b/docs/users_guide/using-optimisation.rst
@@ -979,6 +979,50 @@ by saying ``-fno-wombat``.
     which returns a constrained type. For example, a type class where one
     of the methods implements a traversal.
 
+.. ghc-flag:: -finline-generics
+    :shortdesc: Annotate methods of derived Generic and Generic1 instances with
+        INLINE[1] pragmas based on heuristics. Implied by :ghc-flag:`-O`.
+    :type: dynamic
+    :reverse: -fno-inline-generics
+    :category:
+
+    :default: on
+    :since: 9.2.1
+
+    .. index::
+       single: inlining, controlling
+       single: unfolding, controlling
+
+    Annotate methods of derived Generic and Generic1 instances with INLINE[1]
+    pragmas based on heuristics dependent on the size of the data type in
+    question. Improves performance of generics-based algorithms as GHC is able
+    to optimize away intermediate representation more often.
+
+.. ghc-flag:: -finline-generics-aggressively
+    :shortdesc: Annotate methods of all derived Generic and Generic1 instances
+        with INLINE[1] pragmas.
+    :type: dynamic
+    :reverse: -fno-inline-generics-aggressively
+    :category:
+
+    :default: off
+    :since: 9.2.1
+
+    .. index::
+       single: inlining, controlling
+       single: unfolding, controlling
+
+    Annotate methods of all derived Generic and Generic1 instances with
+    INLINE[1] pragmas.
+
+    This flag should only be used in modules deriving Generic instances that
+    weren't considered appropriate for INLINE[1] annotations by heuristics of
+    :ghc-flag:`-finline-generics`, yet you know that doing so would be
+    beneficial.
+
+    When enabled globally it will most likely lead to worse compile times and
+    code size blowup without runtime performance gains.
+
 .. ghc-flag:: -fsolve-constant-dicts
     :shortdesc: When solving constraints, try to eagerly solve
         super classes using available dictionaries.