Import Upstream version 20180207
[hcoop/debian/mlton.git] / doc / guide / src / DeepFlatten.adoc
1 DeepFlatten
2 ===========
3
4 <:DeepFlatten:> is an optimization pass for the <:SSA2:>
5 <:IntermediateLanguage:>, invoked from <:SSA2Simplify:>.
6
7 == Description ==
8
9 This pass flattens into mutable fields of objects and into vectors.
10
11 For example, an `(int * int) ref` is represented by a 2 word
12 object, and an `(int * int) array` contains pairs of `int`-s,
13 rather than pointers to pairs of `int`-s.
14
15 == Implementation ==
16
17 * <!ViewGitFile(mlton,master,mlton/ssa/deep-flatten.fun)>
18
19 == Details and Notes ==
20
21 There are some performance issues with the deep flatten pass, where it
22 consumes an excessive amount of memory.
23
24 * http://www.mlton.org/pipermail/mlton/2005-April/026990.html
25 * http://www.mlton.org/pipermail/mlton-user/2010-June/001626.html
26 * http://www.mlton.org/pipermail/mlton/2010-December/030876.html
27
28 A number of applications require compilation with
29 `-disable-pass deepFlatten` to avoid exceeding available memory. It is
30 often asked whether the deep flatten pass usually has a significant
31 impact on performance. The standard benchmark suite was run with and
32 without the deep flatten pass enabled when the pass was first
33 introduced:
34
35 * http://www.mlton.org/pipermail/mlton/2004-August/025760.html
36
37 The conclusion is that it does not have a significant impact.
38 However, these are micro benchmarks; other applications may derive
39 greater benefit from the pass.