@@ -1,37 +1,66 @@
11# Compilation Options
22
3−Recommended GHC options are:
3+## Recommended Options
44
5− `-O2 -fdicts-strict -fspec-constr-recursive=16 -fmax-worker-args=16`
5+Benchmarks show that GHC 8.8 has significantly better performance than GHC 8.6
6+in many cases.
67
7−`-fdicts-strict` is needed to avoid [a GHC
8−issue](https://gitlab.haskell.org/ghc/ghc/issues/17745) leading to
9−memory leak in some cases.
8+Use the following GHC options:
109
11−`-fspec-constr-recursive` is needed for better stream fusion by enabling
12−the `SpecConstr` optimization in more cases.
10+```
11+ -O2
12+ -fdicts-strict
13+ -fspec-constr-recursive=16
14+ -fmax-worker-args=16
15+```
1316
14−`-fmax-worker-args` is needed for better stream fusion by enabling the
15−`SpecConstr` optimization in some important cases.
17+## Using Fusion Plugin
18+
19+In many cases `fusion-plugin` can improve performance by better stream
20+fusion. However, in some cases performance may also regress. Please note
21+that the `fusion-plugin` package works only for GHC >= 8.6.
22+
23+* Install the
24+[fusion-plugin](https://hackage.haskell.org/package/fusion-plugin)
25+package or add it to the `build-depends` section of your program in the
26+cabal file.
1627
17−In some cases, you may need to use `-funfolding-use-threshold` to make sure
18−that the combinators fuse. The default value of this option is `60`. Increasing
19−this default value can be detrimental in general, therefore, increase only if
20−you suspect an issue. Hopefully GHC will fix this so that it is not needed in
21−future. Some known examples:
28+* Use the following GHC option in addition to the options listed in the
29+ previous section:
30+
31+```
32+ -fplugin=Fusion.Plugin
33+```
2234
23−* use a value of `75` to fuse `S.chunksOf n (A.writeN n)`.
24−* use a value of `150` to fully fuse `S.splitSuffixOn`.
35+## Minimal
2536
26−At the very least `-O` compilation option is required. In some cases, the
27−program may exhibit memory hog with default optimization options. For example,
28−the following program, if compiled without an optimization option, is known to
29−hog memory:
37+At the very least `-O -fdicts-strict` compilation options are
38+required. If these options are not used, the program may exhibit memory
39+hog. For example, the following program, if compiled without an
40+optimization option, is known to hog memory:
3041
3142```
3243main = S.drain $ S.concatMap S.fromList $ S.repeat []
3344```
3445
46+## Explanation
47+
48+* `-fdicts-strict` is needed to avoid [a GHC
49+issue](https://gitlab.haskell.org/ghc/ghc/issues/17745) leading to
50+memory leak in some cases.
51+
52+* `-fspec-constr-recursive` is needed for better stream fusion by enabling
53+the `SpecConstr` optimization in more cases.
54+
55+* `-fmax-worker-args` is needed for better stream fusion by enabling the
56+`SpecConstr` optimization in some important cases.
57+
58+* `-fplugin=Fusion.Plugin` enables predictable stream fusion
59+optimization in certain cases by helping the compiler inline internal
60+bindings and therefore enabling case-of-case optimization. In some
61+cases, especially in some fileio benchmarks, it can make a difference of
62+5-10x better performance.
63+
3564# Multi-core Parallelism
3665
3766Concurrency without a threaded runtime may be a bit more efficient. Do not use
@@ -42,10 +71,7 @@ multi-core parallelism use the following GHC options:
4271
4372# Compiler Versions
4473
45−GHC 8.8.x seems to have a GC issue which causes space leak in concurrent
46−streams especially when used with `-N` RTS option. The root cause of
47−this has not yet been established. The leak is not seen with earlier
48−versions of GHC.
74+Use GHC 8.8 for best performance.
4975
5076GHC 8.2.2 may hog memory and hang when building certain application using
5177streamly (particularly the benchmark programs in the streamly package).