<!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">

<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 20051202</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>
      &nbsp;<a href = "Index">Index</a>
      &nbsp;
</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&nbsp;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&nbsp;</tt><em>e ...</em><tt>)</tt> 
</p>
</li>
    <li>
<p>
 <tt>(from&nbsp;</tt><em>e</em><tt>)</tt> 
</p>
</li>
    <li>
<p>
 <tt>(not&nbsp;</tt><em>e</em><tt>)</tt> 
</p>
</li>
    <li>
<p>
 <tt>(or&nbsp;</tt><em>e</em><tt>)</tt> 
</p>
</li>
    <li>
<p>
 <tt>(pred&nbsp;</tt><em>e</em><tt>)</tt> 
</p>
</li>
    <li>
<p>
 <tt>(succ&nbsp;</tt><em>e</em><tt>)</tt> 
</p>
</li>
    <li>
<p>
 <tt>(thresh&nbsp;</tt><em>x</em><tt>)</tt> 
</p>
</li>
    <li>
<p>
 <tt>(thresh-gc&nbsp;</tt><em>x</em><tt>)</tt> 
</p>
</li>
    <li>
<p>
 <tt>(thresh-stack&nbsp;</tt><em>x</em><tt>)</tt> 
</p>
</li>
    <li>
<p>
 <tt>(to&nbsp;</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&nbsp;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&nbsp;'(from&nbsp;"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&nbsp;x</tt>, which is an abbreviation for  <tt>-keep&nbsp;'(thresh&nbsp;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&nbsp;true</tt>, you can use  <tt>mlprof&nbsp;-gray&nbsp;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&nbsp;-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>
