<!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>MLtonProfile - 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 20061025</a>
    <td style = "
		border: 0px;
		font-size: 150%;
		text-align: center;
		width: 50%;">
      MLtonProfile
    <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">

<pre class=code>
<B><FONT COLOR="#5F9EA0">signature</FONT></B> MLTON_PROFILE <B><FONT COLOR="#5F9EA0">=</FONT></B>
   <B><FONT COLOR="#5F9EA0">sig</FONT></B>
      <B><FONT COLOR="#5F9EA0">structure</FONT></B> Data:
         <B><FONT COLOR="#5F9EA0">sig</FONT></B>
            <B><FONT COLOR="#A020F0">type</FONT></B> t

            <B><FONT COLOR="#A020F0">val</FONT></B> equals: t <B><FONT COLOR="#5F9EA0">*</FONT></B> t <B><FONT COLOR="#5F9EA0">-</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> <B><FONT COLOR="#228B22">bool</FONT></B>
            <B><FONT COLOR="#A020F0">val</FONT></B> free: t <B><FONT COLOR="#5F9EA0">-</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> <B><FONT COLOR="#228B22">unit</FONT></B>
            <B><FONT COLOR="#A020F0">val</FONT></B> malloc: <B><FONT COLOR="#228B22">unit</FONT></B> <B><FONT COLOR="#5F9EA0">-</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> t
            <B><FONT COLOR="#A020F0">val</FONT></B> write: t <B><FONT COLOR="#5F9EA0">*</FONT></B> <B><FONT COLOR="#228B22">string</FONT></B> <B><FONT COLOR="#5F9EA0">-</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> <B><FONT COLOR="#228B22">unit</FONT></B>
         <B><FONT COLOR="#A020F0">end</FONT></B>

      <B><FONT COLOR="#A020F0">val</FONT></B> isOn: <B><FONT COLOR="#228B22">bool</FONT></B>
      <B><FONT COLOR="#A020F0">val</FONT></B> withData: Data.t <B><FONT COLOR="#5F9EA0">*</FONT></B> (<B><FONT COLOR="#228B22">unit</FONT></B> <B><FONT COLOR="#5F9EA0">-</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> 'a) <B><FONT COLOR="#5F9EA0">-</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> 'a
   <B><FONT COLOR="#A020F0">end</FONT></B>
</PRE>
<p>
 
</p>
<p>
<tt>MLton.Profile</tt> provides <a href="Profiling">Profiling</a> control from within the program, allowing you to profile individual portions of your program. With <tt>MLton.Profile</tt>, you can create many units of profiling data (essentially, mappings from functions to counts) during a run of a program, switch between them while the program is running, and output multiple <tt>mlmon.out</tt> files. 
</p>

    <ul>

    <li>
<p>
 <tt>isOn</tt> 
</p>
</li>

            <ul>

   a compile-time constant that is false only when compiling     <tt>-profile&nbsp;no</tt>. 
            </ul>


    <li class="gap">
<p>
 <tt>type&nbsp;Data.t</tt>  
</p>
</li>

            <ul>

   the type of a unit of profiling data.    In order to most efficiently execute non-profiled programs,    when compiling <tt>-profile&nbsp;no</tt> (the default), <tt>Data.t</tt> is    equivalent to <tt>unit&nbsp;ref</tt>.  
            </ul>


    <li class="gap">
<p>
 <tt>Data.equals&nbsp;(x,&nbsp;y)</tt> 
</p>
</li>

            <ul>

   returns true if the <tt>x</tt> and <tt>y</tt> are the same unit of    profiling data. 
            </ul>


    <li class="gap">
<p>
 <tt>Data.free&nbsp;x</tt> 
</p>
</li>

            <ul>

   frees the memory associated with the unit of profiling data    <tt>x</tt>.  It is an error to free the current unit of profiling data    or to free a previously freed unit of profiling data.  When    compiling <tt>-profile&nbsp;no</tt>, <tt>Data.free&nbsp;x</tt> is a no-op. 
            </ul>


    <li class="gap">
<p>
 <tt>Data.malloc&nbsp;()</tt> 
</p>
</li>

            <ul>

   returns a new unit of profiling data.  Each unit of profiling data    is allocated from the process address space (but is <em>not</em> in the    MLton heap) and consumes memory proportional to the number of    source functions.  When compiling <tt>-profile&nbsp;no</tt>,    <tt>Data.malloc&nbsp;()</tt> is equivalent to allocating a new <tt>unit&nbsp;ref</tt>. 
            </ul>


    <li class="gap">
<p>
 <tt>write&nbsp;(x,&nbsp;f)</tt> 
</p>
</li>

            <ul>

   writes the accumulated ticks in the unit of profiling data <tt>x</tt>    to file <tt>f</tt>.  It is an error to write a previously freed unit    of profiling data.  When compiling <tt>-profile&nbsp;no</tt>,     <tt>write&nbsp;(x,&nbsp;f)</tt> is a no-op.  A profiled program will always    write the current unit of profiling data at program exit to a file    named <tt>mlmon.out</tt>.  
            </ul>


    <li class="gap">
<p>
 <tt>withData&nbsp;(d,&nbsp;f)</tt> 
</p>
</li>

            <ul>

   runs <tt>f</tt> with <tt>d</tt> as the unit of profiling data, and    returns the result of <tt>f</tt> after restoring the current unit of    profiling data.  When compiling <tt>-profile&nbsp;no</tt>,     <tt>withData&nbsp;(d,&nbsp;f)</tt> is equivalent to <tt>f&nbsp;()</tt>. 
            </ul>



    </ul>


<h2 id="head-0f01ed56a1e32a05e5ef96e4d779f34784af9a96">Example</h2>
<p>
Here is an example, taken from the <tt>examples/profiling</tt> directory, showing how to profile the executions of the <tt>fib</tt> and <tt>tak</tt> functions separately.  Suppose that <tt>fib-tak.sml</tt> contains the following. 
</p>

<pre class=code>
<B><FONT COLOR="#5F9EA0">structure</FONT></B> Profile <B><FONT COLOR="#5F9EA0">=</FONT></B> MLton.Profile
   
<B><FONT COLOR="#A020F0">val</FONT></B> fibData <B><FONT COLOR="#5F9EA0">=</FONT></B> Profile.Data.malloc ()
<B><FONT COLOR="#A020F0">val</FONT></B> takData <B><FONT COLOR="#5F9EA0">=</FONT></B> Profile.Data.malloc ()

<B><FONT COLOR="#A020F0">fun </FONT></B><B><FONT COLOR="#0000FF"><B><I><FONT COLOR="#000000">wrap</FONT></I></B></FONT></B> (f, d) x <B><FONT COLOR="#5F9EA0">=</FONT></B>
   Profile.withData (d, <B><FONT COLOR="#A020F0">fn</FONT></B> () <B><FONT COLOR="#5F9EA0">=</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> f x)

<B><FONT COLOR="#A020F0">val</FONT></B> <B><FONT COLOR="#A020F0">rec</FONT></B> fib <B><FONT COLOR="#5F9EA0">=</FONT></B>
   <B><FONT COLOR="#A020F0">fn</FONT></B> 0 <B><FONT COLOR="#5F9EA0">=</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> 0
    <B><FONT COLOR="#5F9EA0">|</FONT></B> 1 <B><FONT COLOR="#5F9EA0">=</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> 1
    <B><FONT COLOR="#5F9EA0">|</FONT></B> n <B><FONT COLOR="#5F9EA0">=</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> fib (n <B><FONT COLOR="#5F9EA0">-</FONT></B> 1) <B><FONT COLOR="#5F9EA0">+</FONT></B> fib (n <B><FONT COLOR="#5F9EA0">-</FONT></B> 2)
<B><FONT COLOR="#A020F0">val</FONT></B> fib <B><FONT COLOR="#5F9EA0">=</FONT></B> wrap (fib, fibData)

<B><FONT COLOR="#A020F0">fun </FONT></B><B><FONT COLOR="#0000FF"><B><I><FONT COLOR="#000000">tak</FONT></I></B></FONT></B> (x,y,z) <B><FONT COLOR="#5F9EA0">=</FONT></B>
   <B><FONT COLOR="#A020F0">if</FONT></B> not (y &lt; x)
      <B><FONT COLOR="#A020F0">then</FONT></B> z
   <B><FONT COLOR="#A020F0">else</FONT></B> tak (tak (x <B><FONT COLOR="#5F9EA0">-</FONT></B> 1, y, z),
             tak (y <B><FONT COLOR="#5F9EA0">-</FONT></B> 1, z, x),
             tak (z <B><FONT COLOR="#5F9EA0">-</FONT></B> 1, x, y))
<B><FONT COLOR="#A020F0">val</FONT></B> tak <B><FONT COLOR="#5F9EA0">=</FONT></B> wrap (tak, takData)

<B><FONT COLOR="#A020F0">val</FONT></B> <B><FONT COLOR="#A020F0">rec</FONT></B> f <B><FONT COLOR="#5F9EA0">=</FONT></B>
   <B><FONT COLOR="#A020F0">fn</FONT></B> 0 <B><FONT COLOR="#5F9EA0">=</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> ()
    <B><FONT COLOR="#5F9EA0">|</FONT></B> n <B><FONT COLOR="#5F9EA0">=</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> (fib 38; f (n<B><FONT COLOR="#5F9EA0">-</FONT></B>1))
<B><FONT COLOR="#A020F0">val</FONT></B> _ <B><FONT COLOR="#5F9EA0">=</FONT></B> f 2

<B><FONT COLOR="#A020F0">val</FONT></B> <B><FONT COLOR="#A020F0">rec</FONT></B> g <B><FONT COLOR="#5F9EA0">=</FONT></B>
   <B><FONT COLOR="#A020F0">fn</FONT></B> 0 <B><FONT COLOR="#5F9EA0">=</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> ()
    <B><FONT COLOR="#5F9EA0">|</FONT></B> n <B><FONT COLOR="#5F9EA0">=</FONT></B><B><FONT COLOR="#5F9EA0">&gt;</FONT></B> (tak (18,12,6); g (n<B><FONT COLOR="#5F9EA0">-</FONT></B>1))
<B><FONT COLOR="#A020F0">val</FONT></B> _ <B><FONT COLOR="#5F9EA0">=</FONT></B> g 500

<B><FONT COLOR="#A020F0">fun </FONT></B><B><FONT COLOR="#0000FF"><B><I><FONT COLOR="#000000">done</FONT></I></B></FONT></B> (data, file) <B><FONT COLOR="#5F9EA0">=</FONT></B>
   (Profile.Data.write (data, file)
    ; Profile.Data.free data)
    
<B><FONT COLOR="#A020F0">val</FONT></B> _ <B><FONT COLOR="#5F9EA0">=</FONT></B> done (fibData, <B><FONT COLOR="#BC8F8F">&quot;mlmon.fib.out&quot;</FONT></B>)
<B><FONT COLOR="#A020F0">val</FONT></B> _ <B><FONT COLOR="#5F9EA0">=</FONT></B> done (takData, <B><FONT COLOR="#BC8F8F">&quot;mlmon.tak.out&quot;</FONT></B>)
</PRE>
<p>
 
</p>
<p>
Compile and run the program. 
</p>

<pre>% mlton -profile time fib-tak.sml
% ./fib-tak
</pre><p>
Separately display the profiling data for <tt>fib</tt>  
</p>

<pre>% mlprof fib-tak mlmon.fib.out
5.77 seconds of CPU time (0.00 seconds GC)
function   cur 
--------- -----
fib       96.9%
&lt;unknown&gt;  3.1%
</pre><p>
and for <tt>tak</tt> 
</p>

<pre>% mlprof fib-tak mlmon.tak.out
0.68 seconds of CPU time (0.00 seconds GC)
function  cur  
-------- ------
tak      100.0%
</pre><p>
Combine the data for <tt>fib</tt> and <tt>tak</tt> by calling <tt>mlprof</tt> with multiple <tt>mlmon.out</tt> files. 
</p>

<pre>% mlprof fib-tak mlmon.fib.out mlmon.tak.out mlmon.out
6.45 seconds of CPU time (0.00 seconds GC)
function   cur 
--------- -----
fib       86.7%
tak       10.5%
&lt;unknown&gt;  2.8%
</pre></div>



<p>
<hr>
Last edited on 2005-12-01 22:21:31 by <span title="ppp-71-139-183-221.dsl.snfc21.pacbell.net"><a href="StephenWeeks">StephenWeeks</a></span>.
</body></html>
