/usr/share/doc/mlton/guide/CallGraph is in mlton-doc 20100608-5.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 | <!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>
|