<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta name="robots" content="index,nofollow">
<title>CallGraph - MLton Standard ML Compiler (SML Compiler)</title>
<link rel="stylesheet" type="text/css" charset="iso-8859-1" media="all" href="common.css">
<link rel="stylesheet" type="text/css" charset="iso-8859-1" media="screen" href="screen.css">
<link rel="stylesheet" type="text/css" charset="iso-8859-1" media="print" href="print.css">
<link rel="Start" href="Home">
</head>
<body lang="en" dir="ltr">
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-833377-1";
urchinTracker();
</script>
<table bgcolor = lightblue cellspacing = 0 style = "border: 0px;" width = 100%>
<tr>
<td style = "
border: 0px;
color: darkblue;
font-size: 150%;
text-align: left;">
<a class = mltona href="Home">MLton MLTONWIKIVERSION</a>
<td style = "
border: 0px;
font-size: 150%;
text-align: center;
width: 50%;">
CallGraph
<td style = "
border: 0px;
text-align: right;">
<table cellspacing = 0 style = "border: 0px">
<tr style = "vertical-align: middle;">
</table>
<tr style = "background-color: white;">
<td colspan = 3
style = "
border: 0px;
font-size:70%;
text-align: right;">
<a href = "Home">Home</a>
<a href = "TitleIndex">Index</a>
</table>
<div id="content" lang="en" dir="ltr">
For easier visualization of <a href="Profiling">profiling</a> data, <tt>mlprof</tt> can create a call graph of the program in dot format, from which you can use the <a class="external" href="http://www.research.att.com/sw/tools/graphviz/"><img src="moin-www.png" alt="[WWW]" height="11" width="11">graphviz</a> software package to create a postscript graph. For example,
<pre>mlprof -call-graph foo.dot foo mlmon.out</pre> will create <tt>foo.dot</tt> 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 <tt>-show-line true</tt>), 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 <tt>mlprof</tt> without any <tt>mlmon.out</tt> files, as in
<pre>mlprof -call-graph foo.dot foo</pre><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>
<p>
Because call graphs can get big, <tt>mlprof</tt> provides the <tt>-keep</tt> option to specify the nodes that you would like to see. This option also controls which functions appear in the table that <tt>mlprof</tt> prints. The argument to <tt>-keep</tt> 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>
<ul>
<li>
<p>
<tt>all</tt>
</p>
</li>
<li>
<p>
"<em>s</em>"
</p>
</li>
<li>
<p>
<tt>(and </tt><em>e ...</em><tt>)</tt>
</p>
</li>
<li>
<p>
<tt>(from </tt><em>e</em><tt>)</tt>
</p>
</li>
<li>
<p>
<tt>(not </tt><em>e</em><tt>)</tt>
</p>
</li>
<li>
<p>
<tt>(or </tt><em>e</em><tt>)</tt>
</p>
</li>
<li>
<p>
<tt>(pred </tt><em>e</em><tt>)</tt>
</p>
</li>
<li>
<p>
<tt>(succ </tt><em>e</em><tt>)</tt>
</p>
</li>
<li>
<p>
<tt>(thresh </tt><em>x</em><tt>)</tt>
</p>
</li>
<li>
<p>
<tt>(thresh-gc </tt><em>x</em><tt>)</tt>
</p>
</li>
<li>
<p>
<tt>(thresh-stack </tt><em>x</em><tt>)</tt>
</p>
</li>
<li>
<p>
<tt>(to </tt><em>e</em><tt>)</tt>
</p>
</li>
</ul>
<p>
In the grammar, <tt>all</tt> denotes the set of all nodes. <tt>"</tt><em>s</em><tt>"</tt> 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 <tt>and</tt>, <tt>not</tt>, and <tt>or</tt> expressions denote intersection, complement, and union, respectively. The <tt>pred</tt> and <tt>succ</tt> expressions add the set of immediate predecessors or successors to their argument, respectively. The <tt>from</tt> and <tt>to</tt> expressions denote the set of nodes that have paths from or to the set of nodes denoted by their arguments, respectively. Finally, <tt>thresh</tt>, <tt>thresh-gc</tt>, and <tt>thresh-stack</tt> 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>
<p>
For example, if you want to see the entire call graph for a program, you can use <tt>-keep all</tt> (this is the default). If you want to see all nodes reachable from function <tt>foo</tt> in your program, you would use <tt>-keep '(from "foo")'</tt>. Or, if you want to see all the functions defined in subdirectory <tt>bar</tt> of your project that used at least 1% of the ticks, you would use
<pre>-keep '(and ".*/bar/" (thresh 1.0))'</pre>To see all functions with ticks above a threshold, you can also use <tt>-thresh x</tt>, which is an abbreviation for <tt>-keep '(thresh x)'</tt>. You can not use multiple <tt>-keep</tt> arguments or both <tt>-keep</tt> and <tt>-thresh</tt>. When you use <tt>-keep</tt> to display a subset of the functions, <tt>mlprof</tt> will add dashed edges to the call graph to indicate a path in the original call graph from one function to another.
</p>
<p>
When compiling with <tt>-profile-stack true</tt>, you can use <tt>mlprof -gray true</tt> to make the nodes darker or lighter depending on whether their stack percentage is higher or lower.
</p>
<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 <tt>mlprof -split</tt> <em>regexp</em>, 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 <tt>General.o</tt>.
</p>
<h2 id="head-bcaa33a7ae44bd5042c37a9cdbea7f843b1cf7c8">Caveats</h2>
<p>
Technically speaking, <tt>mlprof</tt> 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 <tt>f</tt> nontail calls <tt>g</tt> and <tt>g</tt> tail calls <tt>h</tt>, then the call-stack graph has edges from <tt>f</tt> to <tt>g</tt> and <tt>f</tt> to <tt>h</tt>, while the call graph has edges from <tt>f</tt> to <tt>g</tt> and <tt>g</tt> to <tt>h</tt>. That is, a tail call from <tt>g</tt> to <tt>h</tt> removes <tt>g</tt> from the call stack and replaces it with <tt>h</tt>.
</p>
</div>
<p>
<hr>
Last edited on 2005-11-30 23:11:25 by <span title="ppp-71-139-183-221.dsl.snfc21.pacbell.net"><a href="StephenWeeks">StephenWeeks</a></span>.
</body></html>
