diff options
Diffstat (limited to 'docs/users_guide/using-optimisation.rst')
| -rw-r--r-- | docs/users_guide/using-optimisation.rst | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst index ee5b1de95e..0bacf71eb8 100644 --- a/docs/users_guide/using-optimisation.rst +++ b/docs/users_guide/using-optimisation.rst @@ -1423,6 +1423,73 @@ by saying ``-fno-wombat``. determines if a function definition will be kept around at all for potential inlining. +.. ghc-flag:: -funfolding-case-threshold=⟨n⟩ + :shortdesc: *default: 2.* Reduce inlining for cases nested deeper than n. + :type: dynamic + :category: + + :default: 2 + + .. index:: + single: inlining, controlling + single: unfolding, controlling + + GHC is in general quite eager to inline small functions. However sometimes + these functions will be expanded by more inlining after inlining. Since + they are now applied to "interesting" arguments. Even worse, their expanded + form might reference again a small function, which will be inlined and expanded + afterwards. This can repeat often and lead to explosive growth of programs. + + As it happened in #18730. + + Starting with GHC 9.0 we will be less eager to inline deep into nested cases. + We achieve this by applying a inlining penalty that increases as the nesting + gets deeper. However sometimes a specific (maybe quite high!) threshold of nesting + is to be expected. + + In such cases this flag can be used to ignore the first ⟨n⟩ levels of nesting + when computing the penalty. + + This flag in combination with :ghc-flag:`-funfolding-case-scaling=⟨n⟩` can + be used to break inlining loops without disabling inlining completely. For + this purpose a smaller value is more likely to break such loops although + often adjusting the scaling is enough and preferably. + +.. ghc-flag:: -funfolding-case-scaling=⟨n⟩ + :shortdesc: *default: 30.* Apply a penalty of (inlining_cost * `1/n`) for each level of case nesting. + :type: dynamic + :category: + + :default: 30 + + .. index:: + single: inlining, controlling + single: unfolding, controlling + + GHC is in general quite eager to inline small functions. However sometimes + these functions will be expanded by more inlining after inlining. Since + they are now applied to "interesting" arguments. Even worse, their expanded + form might reference again a small function, which will be inlined and expanded + afterwards. This can repeat often and lead to explosive growth of programs. + + As it happened in #18730. + + Starting with GHC 9.0 we will be less eager to inline deep into nested cases. + We achieve this by applying a inlining penalty that increases as the nesting + gets deeper. However sometimes we are ok with inlining a lot in the name of + performance. + + In such cases this flag can be used to tune how hard we penalize inlining into + deeply nested cases beyond the threshold set by :ghc-flag:`-funfolding-case-threshold=⟨n⟩`. + Cases are only counted against the nesting level if they have more than one alternative. + + We use 1/n to scale the penalty. That is a higher value gives a lower penalty. + + This can be used to break inlining loops. For this purpose a lower value is + recommended. Values in the range 10 <= n <= 20 allow some inlining to take place + while still allowing GHC to compile modules containing such inlining loops. + + .. ghc-flag:: -fworker-wrapper :shortdesc: Enable the worker/wrapper transformation. :type: dynamic @@ -1455,3 +1522,5 @@ by saying ``-fno-wombat``. This flag sets the size (in bytes) threshold above which the second approach is used. You can disable the second approach entirely by setting the threshold to 0. + + |