<!DOCTYPE html> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <meta name="generator" content="AsciiDoc 8.6.8"> <title>CallGraph</title> <link rel="stylesheet" href="./asciidoc.css" type="text/css"> <link rel="stylesheet" href="./pygments.css" type="text/css"> <script type="text/javascript" src="./asciidoc.js"></script> <script type="text/javascript"> /*<![CDATA[*/ asciidoc.install(); /*]]>*/ </script> <link rel="stylesheet" href="./mlton.css" type="text/css"/> </head> <body class="article"> <div id="banner"> <div id="banner-home"> <a href="./Home">MLton 20130715</a> </div> </div> <div id="header"> <h1>CallGraph</h1> </div> <div id="content"> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"><p>For easier visualization of <a href="Profiling">profiling</a> data, <span class="monospaced">mlprof</span> can create a call graph of the program in dot format, from which you can use the <a href="http://www.research.att.com/sw/tools/graphviz/">graphviz</a> software package to create a PostScript or PNG graph. For example,</p></div> <div class="listingblock"> <div class="content monospaced"> <pre>mlprof -call-graph foo.dot foo mlmon.out</pre> </div></div> <div class="paragraph"><p>will create <span class="monospaced">foo.dot</span> with a complete call graph. For each source function, there will be one node in the graph that contains the function name (and source position with <span class="monospaced">-show-line true</span>), as well as the percentage of ticks. If you want to create a call graph for your program without any profiling data, you can simply call <span class="monospaced">mlprof</span> without any <span class="monospaced">mlmon.out</span> files, as in</p></div> <div class="listingblock"> <div class="content monospaced"> <pre>mlprof -call-graph foo.dot foo</pre> </div></div> <div class="paragraph"><p>Because SML has higher-order functions, the call graph is is dependent on MLton’s analysis of which functions call each other. This analysis depends on many implementation details and might display spurious edges that a human could conclude are impossible. However, in practice, the call graphs tend to be very accurate.</p></div> <div class="paragraph"><p>Because call graphs can get big, <span class="monospaced">mlprof</span> provides the <span class="monospaced">-keep</span> option to specify the nodes that you would like to see. This option also controls which functions appear in the table that <span class="monospaced">mlprof</span> prints. The argument to <span class="monospaced">-keep</span> is an expression describing a set of source functions (i.e. graph nodes). The expression <em>e</em> should be of the following form.</p></div> <div class="ulist"><ul> <li> <p> <span class="monospaced">all</span> </p> </li> <li> <p> <span class="monospaced">"<em>s</em>"</span> </p> </li> <li> <p> <span class="monospaced">(and <em>e …</em>)</span> </p> </li> <li> <p> <span class="monospaced">(from <em>e</em>)</span> </p> </li> <li> <p> <span class="monospaced">(not <em>e</em>)</span> </p> </li> <li> <p> <span class="monospaced">(or <em>e</em>)</span> </p> </li> <li> <p> <span class="monospaced">(pred <em>e</em>)</span> </p> </li> <li> <p> <span class="monospaced">(succ <em>e</em>)</span> </p> </li> <li> <p> <span class="monospaced">(thresh <em>x</em>)</span> </p> </li> <li> <p> <span class="monospaced">(thresh-gc <em>x</em>)</span> </p> </li> <li> <p> <span class="monospaced">(thresh-stack <em>x</em>)</span> </p> </li> <li> <p> <span class="monospaced">(to <em>e</em>)</span> </p> </li> </ul></div> <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 a regular expression denoting the set of functions whose name (followed by a space and the source position) has a prefix matching the regexp. The <span class="monospaced">and</span>, <span class="monospaced">not</span>, and <span class="monospaced">or</span> expressions denote intersection, complement, and union, respectively. The <span class="monospaced">pred</span> and <span class="monospaced">succ</span> expressions add the set of immediate predecessors or successors to their argument, respectively. The <span class="monospaced">from</span> and <span class="monospaced">to</span> expressions denote the set of nodes that have paths from or to the set of nodes denoted by their arguments, respectively. Finally, <span class="monospaced">thresh</span>, <span class="monospaced">thresh-gc</span>, and <span class="monospaced">thresh-stack</span> denote the set of nodes whose percentage of ticks, gc ticks, or stack ticks, respectively, is greater than or equal to the real number <em>x</em>.</p></div> <div class="paragraph"><p>For example, if you want to see the entire call graph for a program, you can use <span class="monospaced">-keep all</span> (this is the default). If you want to see all nodes reachable from function <span class="monospaced">foo</span> in your program, you would use <span class="monospaced">-keep '(from "foo")'</span>. Or, if you want to see all the functions defined in subdirectory <span class="monospaced">bar</span> of your project that used at least 1% of the ticks, you would use</p></div> <div class="listingblock"> <div class="content monospaced"> <pre>-keep '(and ".*/bar/" (thresh 1.0))'</pre> </div></div> <div class="paragraph"><p>To see all functions with ticks above a threshold, you can also use <span class="monospaced">-thresh x</span>, which is an abbreviation for <span class="monospaced">-keep '(thresh x)'</span>. You can not use multiple <span class="monospaced">-keep</span> arguments or both <span class="monospaced">-keep</span> and <span class="monospaced">-thresh</span>. When you use <span class="monospaced">-keep</span> to display a subset of the functions, <span class="monospaced">mlprof</span> will add dashed edges to the call graph to indicate a path in the original call graph from one function to another.</p></div> <div class="paragraph"><p>When compiling with <span class="monospaced">-profile-stack true</span>, you can use <span class="monospaced">mlprof -gray true</span> to make the nodes darker or lighter depending on whether their stack percentage is higher or lower.</p></div> <div class="paragraph"><p>MLton’s optimizer may duplicate source functions for any of a number of reasons (functor duplication, monomorphisation, polyvariance, inlining). By default, all duplicates of a function are treated as one. If you would like to treat the duplicates separately, you can use <span class="monospaced">mlprof -split <em>regexp</em></span>, which will cause all duplicates of functions whose name has a prefix matching the regular expression to be treated separately. This can be especially useful for higher-order utility functions like <span class="monospaced">General.o</span>.</p></div> </div> </div> <div class="sect1"> <h2 id="_caveats">Caveats</h2> <div class="sectionbody"> <div class="paragraph"><p>Technically speaking, <span class="monospaced">mlprof</span> produces a call-stack graph rather than a call graph, because it describes the set of possible call stacks. The difference is in how tail calls are displayed. For example if <span class="monospaced">f</span> 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 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 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> 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> </div> </div> </div> <div id="footnotes"><hr></div> <div id="footer"> <div id="footer-text"> </div> <div id="footer-badges"> </div> </div> </body> </html>
distrib
>
Fedora
>
18
>
x86_64
>
media
>
updates
>
by-pkgid
>
171636fb720078ab07822dd4a76f1938
>
files
>
2264
