git.iko.soy/streamly
on 678ee5e help sign in
streamly/docs/Build.md
206 lines 8.9 kB history raw
1# GHC Haskell
2## Compiler (GHC) Versions
4For best performance use GHC 8.10 or 8.8 along with `fusion-plugin`
5(see below). Benchmarks show that GHC 8.8 has significantly better
6performance than GHC 8.6 in many cases.
8GHC versions 8.6 onwards are fully supported along with `fusion-plugin`.
9`fusion-plugin` is not supported for GHC versions below 8.6.
11GHC versions 8.0 onwards are supported without `fusion-plugin`. However, note
12that some packages we depend on (e.g. `network`) may support only last three
13major versions of GHC.
15GHC 8.2.2 may hog memory and hang when building certain applications using
16streamly (particularly the benchmark programs in the streamly package).
17Therefore, we recommend avoiding using the GHC version 8.2.x.
19## Memory requirements
21Building streamly itself may require upto 4GB memory. Depending on the
22size of the application you may require 1-16GB memory to build. For most
23applications up to 8GB of memory should be sufficient.
25To reduce the memory footprint you may want to break big modules into
26smaller ones and reduce unnecessary inlining on large functions. You can
27also use the `-Rghc-timing` GHC option to report the memory usage during
28compilation.
30See the "Build times and space considerations" section below for more
31details.
33## Compilation Options
35### Recommended Options
37Add `fusion-plugin` to the `build-depends` section of your program in
38the cabal file and use the following GHC options:
40```
41 -O2
42 -fdicts-strict
43 -fmax-worker-args=16
44 -fspec-constr-recursive=16
45 -fplugin Fusion.Plugin
46```
48Important Notes:
501. [fusion-plugin](https://hackage.haskell.org/package/fusion-plugin) can
51 improve performance significantly by better stream fusion, many
52 cases. If the perform regresses due to fusion-plugin please open
53 an issue. You may remove the `-fplugin` option for regular builds
54 but it is recommended for deployment builds and performance
55 benchmarking. Note, for GHC 8.4 or lower fusion-plugin cannot be used.
562. In certain cases it is possible that GHC takes too long to compile
57 with `-fspec-constr-recursive=16`, if that happens please reduce the
58 value or remove that option.
593. At the very least `-O -fdicts-strict` compilation options are
60 absolutely required to avoid issues in some cases. For example, the
61 program `main = S.drain $ S.concatMap S.fromList $ S.repeat []` may
62 hog memory without these options.
64See [Explanation](#explanation) for details about these flags.
66### Explanation
68* `-fdicts-strict` is needed to avoid [a GHC
69issue](https://gitlab.haskell.org/ghc/ghc/issues/17745) leading to
70memory leak in some cases.
72* `-fspec-constr-recursive` is needed for better stream fusion by enabling
73the `SpecConstr` optimization in more cases. Large values used with this flag
74may lead to huge compilation times and code bloat, if that happens please avoid
75it or use a lower value (e.g. 3 or 4).
77* `-fmax-worker-args` is needed for better stream fusion by enabling the
78`SpecConstr` optimization in some important cases.
80* `-fplugin=Fusion.Plugin` enables predictable stream fusion
81optimization in certain cases by helping the compiler inline internal
82bindings and therefore enabling case-of-case optimization. In some
83cases, especially in some file IO benchmarks, it can make a difference of
845-10x better performance.
86## Multi-core Parallelism
88Concurrency without a threaded runtime may be a bit more efficient. Do not use
89threaded runtime unless you really need multi-core parallelism. To get
90multi-core parallelism use the following GHC options:
92 `-threaded -with-rtsopts "-N"`
94# Platform Specific
96Streamly supports Linux, macOS and Windows operating systems. Some
97modules and functionality may depend on specific OS kernel features.
98Features/modules may get disabled if the kernel/OS does not support it.
100## Linux
102* File system events notification module is supported only for kernel versions
103 2.6.36 onwards.
105## Mac OSX
107* File system events notification module requires macOS 10.7+ with
108 Xcode/macOS SDK installed (depends on `Cocoa` framework). However, we only
109 test on latest three versions of the OS.
111# Performance Optimizations
113A "closed loop" is any streamly code that generates a stream using
114unfold (or conceptually any stream generation combinator) and ends
115up eliminating it with a fold (conceptually any stream elimination
116combinator). It is essentially a loop processing multiple elements in
117a stream sequence, just like a `for` or `while` loop in imperative
118programming.
120Closed loops are generated in a modular fashion by stream generation,
121transformation and elimination combinators in streamly. Combinators
122transfer data to the next stream pipeline stage using data constructors.
123These data constructors are eliminated by the compiler using `stream
124fusion` optimizations, generating a very efficient loop.
126However, stream fusion optimization depends on proper inlining of the
127combinators involved. The fusion-plugin package mentioned earlier
128fills gaps for several optimizations that GHC does not perform
129automatically. It automatically inlines the internal definitions
130that involve the constructors we want to eliminate. In some cases
131fusion-plugin may not help and programmer may have to annotate the code
132manually for complete fusion. In this section we mention some of the
133cases where programmer annotation may help in stream fusion.
135Remember, you need to worry about performance only where it matters, try
136to optimize the fast path and not everything blindly.
138## INLINE annotations
140It may help to add INLINE annotations on any intermediate functions
141involved in a closed loop. In some cases you may have to add an inline
142phase as well as described below.
144Usually GHC has three inline phases - the first phase is pahse-2, the
145second phase is phase-1 and the last one is phase-0.
147### Early INLINE
149Generally, you only have to inline the combinators or functions
150participating in a loop and not the whole loop itself. But sometimes
151you may want to inline the whole loop itself inside a larger
152function. In most cases you can just add an INLINE pragma on
153the function containing the loop. But you may need some special
154considerations in some (not common) cases.
156In some cases you may have to use INLINE[2] instead of INLINE which
157means inline the function early in phase-2. This may sometimes be
158needed on the because the performance of several combinators in streamly
159depends on getting inlined in phase-2 and if you use a plain `INLINE`
160annotation GHC may decide to delay the inlining in some cases. This is
161not very common but may be needed sometimes. Perhaps GHC can be fixed or
162we can resolve this using fusion-plugin in future.
164### Delayed INLINE
166When a function is passed to a higher order function e.g. a function
167passed to `concatMap` or `concatUnfold` then we want the function to be
168inlined after the higher order is inlined so that proper fusion of the
169higher order function can occur. For such cases we usually add INLINE[1]
170on the function being passed to instruct GHC not to inline it too early.
172## Strictness annotations
174* Strictness annotations on data, specially the data used as accumulator in
175 folds and scans, can help in improving performance.
176* Strictness annotations on function arguments can help the compiler unbox
177 constructors in certain cases, improving performance.
178* Sometimes using `-XStrict` extension can help improve performance, if so you
179 may be missing some strictness annotations. `-XStrict` can be used as an aid
180 to detect missing annotations, using it blindly may regress performance.
182## Use tail recursion
184Do not use a strict `foldr` or lazy `foldl` unless you know what you are
185doing. Use lazy `foldr` for lazily transforming the stream and strict
186`foldl` for reducing the stream. If you are manually writing recursive
187code, try to use tail recursion where possible.
189# Build times and space considerations
191Haskell, being a pure functional language, confers special powers on
192GHC. It allows GHC to do whole program optimization. In a closed loop
193all the components of the loop are inlined and GHC fuses them together,
194performs many optimizing transformations and churns out an optimized
195fused loop code. Let's call it whole-loop-optimization.
197To be able to fuse the loop by whole-loop-optimization all the parts of the
198loop must be operated on by GHC at the same time to fuse them together. The
199amount of time and memory required to do so depends on the size of the loop.
200Huge loops can take a lot of time and memory. We have seen GHC take 4-5 GB of
201memory when a lot of combinators are used in a single module.
203If a module takes too much time and space we can break it into multiple
204modules moving some non-inlined parts in another module. There is
205another advantage of breaking large modules, it can take advantage of
206parallel compilation if they do not depend on each other.