GitLab

Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC

Commits:

a7f15858

by sheaf at 2025-09-24T09:49:53-04:00

User's guide: clarify optimisation of INLINABLE unfoldings

This updates the user's guide section on INLINABLE pragmas to explain how
the unfoldings of inlineable functions are optimised. The user's guide incorrectly
stated that the RHS was not optimised at all, but this is not true. Instead, GHC
is careful about phase control to optmise the RHS while retaining the guarantee
that GHC behaves as if the original RHS had been written.

1 changed file:

docs/users_guide/exts/pragmas.rst

Changes:

docs/users_guide/exts/pragmas.rst

@@ -486,17 +486,18 @@ behaviour:
     optimisation level etc.
  -  Like ``INLINE``, the ``INLINABLE`` pragma retains a copy of the
 -   original RHS for inlining purposes, and persists it in the interface
 +   RHS for inlining purposes, and persists it in the interface
     file, regardless of the size of the RHS.
 +   The RHS will be carefully optimised so that, when the function
 +   inlines, GHC behaves as if the original RHS had been inlined.
  -  One way to use ``INLINABLE`` is in conjunction with the special
     function ``inline`` (:ref:`special-ids`). The call ``inline f`` tries
     very hard to inline ``f``. To make sure that ``f`` can be inlined, it
     is a good idea to mark the definition of ``f`` as ``INLINABLE``, so
     that GHC guarantees to expose an unfolding regardless of how big it
 -   is. Moreover, by annotating ``f`` as ``INLINABLE``, you ensure that
 -   ``f``\'s original RHS is inlined, rather than whatever random
 -   optimised version of ``f`` GHC's optimiser has produced.
 +   is. You can also provide an explicit :ref:`phase-control` on the
 +   ``INLINABLE`` pragma to ensure that RULES have a chance of firing first.
  -  The ``INLINABLE`` pragma also works with ``SPECIALISE``: if you mark
     function ``f`` as ``INLINABLE``, then you can subsequently