| | 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 |
HCoop / hcoop / debian / mlton.git / blame_incremental