Commit | Line | Data |
---|---|---|
7f918cf1 CE |
1 | <!DOCTYPE html>\r |
2 | <html lang="en">\r | |
3 | <head>\r | |
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">\r | |
5 | <meta name="generator" content="AsciiDoc 8.6.9">\r | |
6 | <title>CallGraph</title>\r | |
7 | <link rel="stylesheet" href="./asciidoc.css" type="text/css">\r | |
8 | <link rel="stylesheet" href="./pygments.css" type="text/css">\r | |
9 | \r | |
10 | \r | |
11 | <script type="text/javascript" src="./asciidoc.js"></script>\r | |
12 | <script type="text/javascript">\r | |
13 | /*<![CDATA[*/\r | |
14 | asciidoc.install();\r | |
15 | /*]]>*/\r | |
16 | </script>\r | |
17 | <link rel="stylesheet" href="./mlton.css" type="text/css">\r | |
18 | </head>\r | |
19 | <body class="article">\r | |
20 | <div id="banner">\r | |
21 | <div id="banner-home">\r | |
22 | <a href="./Home">MLton 20180207</a>\r | |
23 | </div>\r | |
24 | </div>\r | |
25 | <div id="header">\r | |
26 | <h1>CallGraph</h1>\r | |
27 | </div>\r | |
28 | <div id="content">\r | |
29 | <div id="preamble">\r | |
30 | <div class="sectionbody">\r | |
31 | <div class="paragraph"><p>For easier visualization of <a href="Profiling">profiling</a> data, <span class="monospaced">mlprof</span> can\r | |
32 | create a call graph of the program in dot format, from which you can\r | |
33 | use the <a href="http://www.research.att.com/sw/tools/graphviz/">graphviz</a>\r | |
34 | software package to create a PostScript or PNG graph. For example,</p></div>\r | |
35 | <div class="listingblock">\r | |
36 | <div class="content monospaced">\r | |
37 | <pre>mlprof -call-graph foo.dot foo mlmon.out</pre>\r | |
38 | </div></div>\r | |
39 | <div class="paragraph"><p>will create <span class="monospaced">foo.dot</span> with a complete call graph. For each source\r | |
40 | function, there will be one node in the graph that contains the\r | |
41 | function name (and source position with <span class="monospaced">-show-line true</span>), as\r | |
42 | well as the percentage of ticks. If you want to create a call graph\r | |
43 | for your program without any profiling data, you can simply call\r | |
44 | <span class="monospaced">mlprof</span> without any <span class="monospaced">mlmon.out</span> files, as in</p></div>\r | |
45 | <div class="listingblock">\r | |
46 | <div class="content monospaced">\r | |
47 | <pre>mlprof -call-graph foo.dot foo</pre>\r | |
48 | </div></div>\r | |
49 | <div class="paragraph"><p>Because SML has higher-order functions, the call graph is is dependent\r | |
50 | on MLton’s analysis of which functions call each other. This analysis\r | |
51 | depends on many implementation details and might display spurious\r | |
52 | edges that a human could conclude are impossible. However, in\r | |
53 | practice, the call graphs tend to be very accurate.</p></div>\r | |
54 | <div class="paragraph"><p>Because call graphs can get big, <span class="monospaced">mlprof</span> provides the <span class="monospaced">-keep</span> option\r | |
55 | to specify the nodes that you would like to see. This option also\r | |
56 | controls which functions appear in the table that <span class="monospaced">mlprof</span> prints.\r | |
57 | The argument to <span class="monospaced">-keep</span> is an expression describing a set of source\r | |
58 | functions (i.e. graph nodes). The expression <em>e</em> should be of the\r | |
59 | following form.</p></div>\r | |
60 | <div class="ulist"><ul>\r | |
61 | <li>\r | |
62 | <p>\r | |
63 | <span class="monospaced">all</span>\r | |
64 | </p>\r | |
65 | </li>\r | |
66 | <li>\r | |
67 | <p>\r | |
68 | <span class="monospaced">"<em>s</em>"</span>\r | |
69 | </p>\r | |
70 | </li>\r | |
71 | <li>\r | |
72 | <p>\r | |
73 | <span class="monospaced">(and <em>e …</em>)</span>\r | |
74 | </p>\r | |
75 | </li>\r | |
76 | <li>\r | |
77 | <p>\r | |
78 | <span class="monospaced">(from <em>e</em>)</span>\r | |
79 | </p>\r | |
80 | </li>\r | |
81 | <li>\r | |
82 | <p>\r | |
83 | <span class="monospaced">(not <em>e</em>)</span>\r | |
84 | </p>\r | |
85 | </li>\r | |
86 | <li>\r | |
87 | <p>\r | |
88 | <span class="monospaced">(or <em>e</em>)</span>\r | |
89 | </p>\r | |
90 | </li>\r | |
91 | <li>\r | |
92 | <p>\r | |
93 | <span class="monospaced">(pred <em>e</em>)</span>\r | |
94 | </p>\r | |
95 | </li>\r | |
96 | <li>\r | |
97 | <p>\r | |
98 | <span class="monospaced">(succ <em>e</em>)</span>\r | |
99 | </p>\r | |
100 | </li>\r | |
101 | <li>\r | |
102 | <p>\r | |
103 | <span class="monospaced">(thresh <em>x</em>)</span>\r | |
104 | </p>\r | |
105 | </li>\r | |
106 | <li>\r | |
107 | <p>\r | |
108 | <span class="monospaced">(thresh-gc <em>x</em>)</span>\r | |
109 | </p>\r | |
110 | </li>\r | |
111 | <li>\r | |
112 | <p>\r | |
113 | <span class="monospaced">(thresh-stack <em>x</em>)</span>\r | |
114 | </p>\r | |
115 | </li>\r | |
116 | <li>\r | |
117 | <p>\r | |
118 | <span class="monospaced">(to <em>e</em>)</span>\r | |
119 | </p>\r | |
120 | </li>\r | |
121 | </ul></div>\r | |
122 | <div class="paragraph"><p>In the grammar, <span class="monospaced">all</span> denotes the set of all nodes. <span class="monospaced">"<em>s</em>"</span> is\r | |
123 | a regular expression denoting the set of functions whose name\r | |
124 | (followed by a space and the source position) has a prefix matching\r | |
125 | the regexp. The <span class="monospaced">and</span>, <span class="monospaced">not</span>, and <span class="monospaced">or</span> expressions denote\r | |
126 | intersection, complement, and union, respectively. The <span class="monospaced">pred</span> and\r | |
127 | <span class="monospaced">succ</span> expressions add the set of immediate predecessors or successors\r | |
128 | to their argument, respectively. The <span class="monospaced">from</span> and <span class="monospaced">to</span> expressions\r | |
129 | denote the set of nodes that have paths from or to the set of nodes\r | |
130 | denoted by their arguments, respectively. Finally, <span class="monospaced">thresh</span>,\r | |
131 | <span class="monospaced">thresh-gc</span>, and <span class="monospaced">thresh-stack</span> denote the set of nodes whose\r | |
132 | percentage of ticks, gc ticks, or stack ticks, respectively, is\r | |
133 | greater than or equal to the real number <em>x</em>.</p></div>\r | |
134 | <div class="paragraph"><p>For example, if you want to see the entire call graph for a program,\r | |
135 | you can use <span class="monospaced">-keep all</span> (this is the default). If you want to see\r | |
136 | all nodes reachable from function <span class="monospaced">foo</span> in your program, you would\r | |
137 | use <span class="monospaced">-keep '(from "foo")'</span>. Or, if you want to see all the\r | |
138 | functions defined in subdirectory <span class="monospaced">bar</span> of your project that used\r | |
139 | at least 1% of the ticks, you would use</p></div>\r | |
140 | <div class="listingblock">\r | |
141 | <div class="content monospaced">\r | |
142 | <pre>-keep '(and ".*/bar/" (thresh 1.0))'</pre>\r | |
143 | </div></div>\r | |
144 | <div class="paragraph"><p>To see all functions with ticks above a threshold, you can also use\r | |
145 | <span class="monospaced">-thresh x</span>, which is an abbreviation for <span class="monospaced">-keep '(thresh x)'</span>. You\r | |
146 | can not use multiple <span class="monospaced">-keep</span> arguments or both <span class="monospaced">-keep</span> and <span class="monospaced">-thresh</span>.\r | |
147 | When you use <span class="monospaced">-keep</span> to display a subset of the functions, <span class="monospaced">mlprof</span>\r | |
148 | will add dashed edges to the call graph to indicate a path in the\r | |
149 | original call graph from one function to another.</p></div>\r | |
150 | <div class="paragraph"><p>When compiling with <span class="monospaced">-profile-stack true</span>, you can use <span class="monospaced">mlprof -gray\r | |
151 | true</span> to make the nodes darker or lighter depending on whether their\r | |
152 | stack percentage is higher or lower.</p></div>\r | |
153 | <div class="paragraph"><p>MLton’s optimizer may duplicate source functions for any of a number\r | |
154 | of reasons (functor duplication, monomorphisation, polyvariance,\r | |
155 | inlining). By default, all duplicates of a function are treated as\r | |
156 | one. If you would like to treat the duplicates separately, you can\r | |
157 | use <span class="monospaced">mlprof -split <em>regexp</em></span>, which will cause all duplicates of\r | |
158 | functions whose name has a prefix matching the regular expression to\r | |
159 | be treated separately. This can be especially useful for higher-order\r | |
160 | utility functions like <span class="monospaced">General.o</span>.</p></div>\r | |
161 | </div>\r | |
162 | </div>\r | |
163 | <div class="sect1">\r | |
164 | <h2 id="_caveats">Caveats</h2>\r | |
165 | <div class="sectionbody">\r | |
166 | <div class="paragraph"><p>Technically speaking, <span class="monospaced">mlprof</span> produces a call-stack graph rather than\r | |
167 | a call graph, because it describes the set of possible call stacks.\r | |
168 | The difference is in how tail calls are displayed. For example if <span class="monospaced">f</span>\r | |
169 | nontail calls <span class="monospaced">g</span> and <span class="monospaced">g</span> tail calls <span class="monospaced">h</span>, then the call-stack graph\r | |
170 | has edges from <span class="monospaced">f</span> to <span class="monospaced">g</span> and <span class="monospaced">f</span> to <span class="monospaced">h</span>, while the call graph has\r | |
171 | edges from <span class="monospaced">f</span> to <span class="monospaced">g</span> and <span class="monospaced">g</span> to <span class="monospaced">h</span>. That is, a tail call from <span class="monospaced">g</span>\r | |
172 | to <span class="monospaced">h</span> removes <span class="monospaced">g</span> from the call stack and replaces it with <span class="monospaced">h</span>.</p></div>\r | |
173 | </div>\r | |
174 | </div>\r | |
175 | </div>\r | |
176 | <div id="footnotes"><hr></div>\r | |
177 | <div id="footer">\r | |
178 | <div id="footer-text">\r | |
179 | </div>\r | |
180 | <div id="footer-badges">\r | |
181 | </div>\r | |
182 | </div>\r | |
183 | </body>\r | |
184 | </html>\r |