[Git][ghc/ghc][wip/andreask/inline-docs] Clarify INLINE unfolding optimization docs.

[Andreas Klebinger (@AndreasK)]

Andreas Klebinger pushed to branch wip/andreask/inline-docs at Glasgow Haskell Compiler / GHC


Commits:
be2360b7 by Andreas Klebinger at 2024-11-18T13:23:50+01:00
Clarify INLINE unfolding optimization docs.

Fixes #24660

- - - - -


1 changed file:

- docs/users_guide/exts/pragmas.rst


Changes:

=====================================
docs/users_guide/exts/pragmas.rst
=====================================
@@ -393,12 +393,15 @@ has a number of other effects:
    pragmas is to expose functions in ``f``\'s RHS that have rewrite
    rules, and it's no good if those functions have been optimised away.
 
-   So *GHC guarantees to inline precisely the code that you wrote*, no
-   more and no less. It does this by capturing a copy of the definition
+   So *GHC guarantees to behave precisely as if it inlined the code that you wrote*.
+   It does this by capturing a copy of the definition
    of the function to use for inlining (we call this the "inline-RHS"),
-   which it leaves untouched, while optimising the ordinarily RHS as
-   usual. For externally-visible functions the inline-RHS (not the
-   optimised RHS) is recorded in the interface file.
+   which it only optimizes in ways which don't break this promise.
+   For example if inlining is explicitly delayed through phase control GHC will
+   apply optimizations which happen before the ``INLINE`` pragma becomes
+   active to the inline-RHS while optimising the ordinarily RHS as usual.
+   For externally-visible functions
+   the inline-RHS (not the optimised RHS) is recorded in the interface file.
 
 -  An ``INLINE`` function is not worker/wrappered by strictness analysis.
    It's going to be inlined wholesale instead.



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/be2360b7849a865e0f1b98129621f6d856fb34e5

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/be2360b7849a865e0f1b98129621f6d856fb34e5
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20241118/74cac768/attachment-0001.html>