fusion-plugin: GHC plugin to make stream fusion more predictable.
This plugin provides the programmer with a way to annotate certain
types using a Fuse pragma from the
fusion-plugin-types
package. The programmer would annotate the types that are to be
eliminated by fusion. During the simplifier phase the plugin goes
through the relevant bindings and if one of these types are found
inside a binding then that binding is marked to be inlined
irrespective of the size.
This plugin was primarily motivated by streamly but it can be used in general.
[Skip to Readme]
Downloads
- fusion-plugin-0.2.7.tar.gz [browse] (Cabal source package)
- Package description (revised from the package)
Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.
Maintainer's Corner
For package maintainers and hackage trustees
Candidates
- No Candidates
| Versions [RSS] | 0.1.0, 0.1.1, 0.2.0, 0.2.1, 0.2.2, 0.2.3, 0.2.4, 0.2.5, 0.2.6, 0.2.7 |
|---|---|
| Change log | CHANGELOG.md |
| Dependencies | base (>=4.0 && <5.0), containers (>=0.5.6.2 && <0.8), directory (>=1.2.2.0 && <1.4), filepath (>=1.4 && <1.6), fusion-plugin-types (>=0.1 && <0.2), ghc (>=7.10.3 && <9.11), syb (>=0.7 && <0.8), time (>=1.5 && <1.14), transformers (>=0.4 && <0.7) [details] |
| Tested with | ghc ==8.6.5, ghc ==8.8.4, ghc ==8.10.7, ghc ==9.0.2, ghc ==9.2.8, ghc ==9.4.7, ghc ==9.6.3, ghc ==9.8.1 |
| License | Apache-2.0 |
| Copyright | (c) 2019 Composewell Technologies |
| Author | Pranay Sashank |
| Maintainer | streamly@composewell.com |
| Revised | Revision 3 made by adithyaov at 2024-07-15T13:06:35Z |
| Category | Development |
| Home page | https://github.com/composewell/fusion-plugin |
| Bug tracker | https://github.com/composewell/fusion-plugin/issues |
| Source repo | head: git clone https://github.com/composewell/fusion-plugin |
| Uploaded | by harendra at 2023-11-01T12:47:27Z |
| Distributions | LTSHaskell:0.2.7, NixOS:0.2.7, Stackage:0.2.7 |
| Reverse Dependencies | 1 direct, 0 indirect [details] |
| Downloads | 2988 total (34 in the last 30 days) |
| Rating | 2.0 (votes: 1) [estimated by Bayesian average] |
| Your Rating | |
| Status | Docs available [build log] Last success reported on 2023-11-01 [all 1 reports] |
Readme for fusion-plugin-0.2.7
[back to package description]fusion-plugin
Motivation
The goal of stream fusion is to eliminate constructors of
internal state used in a stream. For example, in case of
streamly streams, the
constructors of Step type, Yield, Skip and Stop would get
eliminated by fusion. Similarly, constructors of any other intermediate
state types get eliminated when stream fusion works correctly. See the papers
in the reference section for more details on stream fusion.
Stream fusion depends on the GHC case-of-case transformations eliminating intermediate constructors. Case-of-case transformation in turn depends on inlining. During core-to-core transformations GHC may create several internal bindings (e.g. join points) which may not get inlined because their size is too big. Even though we know that after fusion the resulting code would be smaller and more efficient. The programmer cannot force inlining of these bindings as there is no way for the programmer to address these bindings at the source level because they are internal, generated during core-to-core transformations. As a result stream fusion fails unpredictably depending on whether GHC was able to inline the internal bindings or not.
See GHC ticket #17075 for more details.
Solution
This plugin provides the programmer with a way to annotate certain
types using a Fuse pragma from the
fusion-plugin-types
package. The programmer would annotate the types that are to be
eliminated by fusion. During the simplifier phase the plugin goes
through the relevant bindings and if one of these types are found
inside a binding then that binding is marked to be inlined
irrespective of the size.
Using the plugin
This plugin was primarily motivated by streamly but it can be used in general.
To use this plugin, add this package to your build-depends
and pass the following to your ghc-options:
ghc-options: -O2 -fplugin=Fusion.Plugin
Plugin options
Note: dump-core does not work for GHC-9.0.x, 9.6.x and 9.8.x.
-fplugin-opt=Fusion.Plugin:dump-core: dump core after each
core-to-core transformation. Output from each transformation is printed
in a different file.
-fplugin-opt=Fusion.Plugin:verbose=1: report unfused functions. Verbosity
levels 2, 3, 4 can be used for more verbose output.
See also
If you are a library author looking to annotate the types, you need to use the fusion-plugin-types package.
Contributing
All contributions are welcome! The code is available under Apache-2.0 license on github. In case you have any questions or suggestions please contact the maintainers.
We would be happy to see this work getting integrated with GHC as a fix for GHC ticket #17075, any help with that would be appreciated.