ruby-prof 0.15.4 → 0.15.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dad7c2ed1d68e57959ca77403a8ac342aca2e109
-  data.tar.gz: 386143d988c94f456253ad76526dc217a86c8177
+  metadata.gz: 6bca6fbb93e0558298aa5d30d8a8771d116ddbf5
+  data.tar.gz: 8b908920d2cc8192011c43eea35f84bc2042a0a3
 SHA512:
-  metadata.gz: ac5904bacc7110dd78a0f75b86095ee1767e337abb22399f4476b0644056279515f0c1e6e13d32518d0ef3392a39acee3a9b2aa507f91598f57cfa8b3a32aca7
-  data.tar.gz: 9090e101f0dd1cc78c6125d57386324d6da3288bf88afc7b3618fd8c71f37fdc68211e06d6e0512df6149ca6fddd137100efe8c40248f5a505050839a4207b5f
+  metadata.gz: 1a358dd828584635f1d2141696971ca50db1829171f8808a8c00a1783b2a43ff91b1148269f0146b7d10cbf972401013085db4c3ff91b8b845947784558bdc1e
+  data.tar.gz: 7e4564d1c5d452561f1067faac32cab8dd896ee8d5627b6534c3894fb122860779e73d40fe95822ec2d63cd4ff60908233510ff867e430d772b824495fce87df

data/CHANGES

@@ -1,4 +1,10 @@
-0.15.4 (2014-05-20)
+0.15.5 (2015-02-22)
+======================
+* improved upon computing children time in graph printers
+* changed output format of flat_printer_with_line_number
+* support using multi printer from command line (Dov Murik)
+
+0.15.4 (2015-02-14)
 ======================
 * using env variable to specify mesaurement mode work again
 * measuring memory/object allocations works for 2.1 adn 2.2 again

data/README.rdoc

@@ -203,7 +203,7 @@ ruby-prof can generate a number of different reports:
 * More!
 
 Flat profiles show the overall time spent in each method. They
-are a good of quickly identifying which methods take the most time.
+are a good way of quickly identifying which methods take the most time.
 An example of a flat profile and an explanation can be found in
 {examples/flat.txt}[http://github.com/ruby-prof/ruby-prof/tree/master/examples/flat.txt].
 

data/bin/ruby-prof

@@ -53,7 +53,7 @@ module RubyProf
         opts.separator ""
         opts.separator "Options:"
 
-        opts.on('-p printer', '--printer=printer', [:flat, :flat_with_line_numbers, :graph, :graph_html, :call_tree, :call_stack, :dot],
+        opts.on('-p printer', '--printer=printer', [:flat, :flat_with_line_numbers, :graph, :graph_html, :call_tree, :call_stack, :dot, :multi],
                 'Select a printer:',
                 '  flat - Prints a flat profile as text (default).',
                 '  flat_with_line_numbers - same as flat, with line numbers.',
@@ -61,7 +61,8 @@ module RubyProf
                 '  graph_html - Prints a graph profile as html.',
                 '  call_tree - format for KCacheGrind',
                 '  call_stack - prints a HTML visualization of the call tree',
-                '  dot - Prints a graph profile as a dot file'
+                '  dot - Prints a graph profile as a dot file',
+                '  multi - Creates several reports in output directory'
         ) do |printer|
 
 
@@ -80,6 +81,8 @@ module RubyProf
             options.printer = RubyProf::CallStackPrinter
           when :dot
             options.printer = RubyProf::DotPrinter
+          when :multi
+            options.printer = RubyProf::MultiPrinter
           end
         end
 
@@ -246,6 +249,11 @@ module RubyProf
       end
 
       self.option_parser.parse! ARGV
+
+      if options.printer == RubyProf::MultiPrinter
+        options.file ||= "."
+        options.old_wd ||= Dir.pwd
+      end
     rescue OptionParser::InvalidOption, OptionParser::InvalidArgument, OptionParser::MissingArgument => e
       puts self.option_parser
       puts e.message
@@ -314,8 +322,12 @@ at_exit {
   if cmd.options.file
     # write it relative to the dir they *started* in, as it's a bit surprising to write it in the dir they end up in.
     Dir.chdir(cmd.options.old_wd) do
-      File.open(cmd.options.file, 'w') do |file|
-        printer.print(file, printer_options)
+      if printer.is_a?(RubyProf::MultiPrinter)
+        printer.print(printer_options.merge(:path => cmd.options.file))
+      else
+        File.open(cmd.options.file, 'w') do |file|
+          printer.print(file, printer_options)
+        end
       end
     end
   else

data/doc/LICENSE.html

@@ -0,0 +1,114 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+<meta charset="UTF-8">
+
+<title>LICENSE - ruby-prof</title>
+
+<script type="text/javascript">
+  var rdoc_rel_prefix = "./";
+</script>
+
+<script src="./js/jquery.js"></script>
+<script src="./js/darkfish.js"></script>
+
+<link href="./css/fonts.css" rel="stylesheet">
+<link href="./css/rdoc.css" rel="stylesheet">
+
+
+
+<body id="top" role="document" class="file">
+<nav role="navigation">
+  <div id="project-navigation">
+    <div id="home-section" role="region" title="Quick navigation" class="nav-section">
+  <h2>
+    <a href="./index.html" rel="home">Home</a>
+  </h2>
+
+  <div id="table-of-contents-navigation">
+    <a href="./table_of_contents.html#pages">Pages</a>
+    <a href="./table_of_contents.html#classes">Classes</a>
+    <a href="./table_of_contents.html#methods">Methods</a>
+  </div>
+</div>
+
+    <div id="search-section" role="search" class="project-section initially-hidden">
+  <form action="#" method="get" accept-charset="utf-8">
+    <div id="search-field-wrapper">
+      <input id="search-field" role="combobox" aria-label="Search"
+             aria-autocomplete="list" aria-controls="search-results"
+             type="text" name="search" placeholder="Search" spellcheck="false"
+             title="Type to search, Up and Down to navigate, Enter to load">
+    </div>
+
+    <ul id="search-results" aria-label="Search Results"
+        aria-busy="false" aria-expanded="false"
+        aria-atomic="false" class="initially-hidden"></ul>
+  </form>
+</div>
+
+  </div>
+
+  
+
+  <div id="project-metadata">
+    <div id="fileindex-section" class="nav-section">
+  <h3>Pages</h3>
+
+  <ul class="link-list">
+  
+    <li><a href="./LICENSE.html">LICENSE</a>
+  
+    <li><a href="./README_rdoc.html">README</a>
+  
+    <li><a href="./examples/flat_txt.html">flat</a>
+  
+    <li><a href="./examples/graph_html.html">graph.html</a>
+  
+    <li><a href="./examples/graph_txt.html">graph</a>
+  
+  </ul>
+</div>
+
+  </div>
+</nav>
+
+<main role="main" aria-label="Page LICENSE">
+
+<p>Copyright (C) 2005 - 2014 Shugo Maeda &lt;shugo@ruby-lang.org&gt; and
+Charlie Savage &lt;cfis@savagexi.com&gt; Copyright (C) 2010 - 2014 Stefan
+Kaes &lt;skaes@railsepxress.de&gt; All rights reserved.</p>
+
+<p>Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:</p>
+<ol><li>
+<p>Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.</p>
+</li><li>
+<p>Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.</p>
+</li></ol>
+
+<p>THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS “AS IS&#39;&#39;
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.</p>
+</main>
+
+
+
+<footer id="validator-badges" role="contentinfo">
+  <p><a href="http://validator.w3.org/check/referer">Validate</a>
+  <p>Generated by <a href="http://docs.seattlerb.org/rdoc/">RDoc</a> 4.2.0.
+  <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
+</footer>
+

data/doc/README_rdoc.html

@@ -0,0 +1,592 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+<meta charset="UTF-8">
+
+<title>README - ruby-prof</title>
+
+<script type="text/javascript">
+  var rdoc_rel_prefix = "./";
+</script>
+
+<script src="./js/jquery.js"></script>
+<script src="./js/darkfish.js"></script>
+
+<link href="./css/fonts.css" rel="stylesheet">
+<link href="./css/rdoc.css" rel="stylesheet">
+
+
+
+<body id="top" role="document" class="file">
+<nav role="navigation">
+  <div id="project-navigation">
+    <div id="home-section" role="region" title="Quick navigation" class="nav-section">
+  <h2>
+    <a href="./index.html" rel="home">Home</a>
+  </h2>
+
+  <div id="table-of-contents-navigation">
+    <a href="./table_of_contents.html#pages">Pages</a>
+    <a href="./table_of_contents.html#classes">Classes</a>
+    <a href="./table_of_contents.html#methods">Methods</a>
+  </div>
+</div>
+
+    <div id="search-section" role="search" class="project-section initially-hidden">
+  <form action="#" method="get" accept-charset="utf-8">
+    <div id="search-field-wrapper">
+      <input id="search-field" role="combobox" aria-label="Search"
+             aria-autocomplete="list" aria-controls="search-results"
+             type="text" name="search" placeholder="Search" spellcheck="false"
+             title="Type to search, Up and Down to navigate, Enter to load">
+    </div>
+
+    <ul id="search-results" aria-label="Search Results"
+        aria-busy="false" aria-expanded="false"
+        aria-atomic="false" class="initially-hidden"></ul>
+  </form>
+</div>
+
+  </div>
+
+  
+<div class="nav-section">
+  <h3>Table of Contents</h3>
+
+  <ul class="link-list" role="directory">
+    <li><a href="#label-ruby-prof">ruby-prof</a>
+    <li><a href="#label-Overview">Overview</a>
+    <li><a href="#label-Requirements">Requirements</a>
+    <li><a href="#label-Install">Install</a>
+    <li><a href="#label-Usage">Usage</a>
+    <li><a href="#label-ruby-prof+executable">ruby-prof executable</a>
+    <li><a href="#label-ruby-prof+API">ruby-prof API</a>
+    <li><a href="#label-Method+and+Thread+Elimination">Method and Thread Elimination</a>
+    <li><a href="#label-Benchmarking+full+load+time+including+rubygems+startup+cost">Benchmarking full load time including rubygems startup cost</a>
+    <li><a href="#label-Profiling+Rails">Profiling Rails</a>
+    <li><a href="#label-Reports">Reports</a>
+    <li><a href="#label-Printers">Printers</a>
+    <li><a href="#label-Measurements">Measurements</a>
+    <li><a href="#label-Multi-threaded+Applications">Multi-threaded Applications</a>
+    <li><a href="#label-Performance">Performance</a>
+    <li><a href="#label-License">License</a>
+    <li><a href="#label-Development">Development</a>
+  </ul>
+</div>
+
+
+  <div id="project-metadata">
+    <div id="fileindex-section" class="nav-section">
+  <h3>Pages</h3>
+
+  <ul class="link-list">
+  
+    <li><a href="./LICENSE.html">LICENSE</a>
+  
+    <li><a href="./README_rdoc.html">README</a>
+  
+    <li><a href="./examples/flat_txt.html">flat</a>
+  
+    <li><a href="./examples/graph_html.html">graph.html</a>
+  
+    <li><a href="./examples/graph_txt.html">graph</a>
+  
+  </ul>
+</div>
+
+  </div>
+</nav>
+
+<main role="main" aria-label="Page README.rdoc">
+
+<h1 id="label-ruby-prof">ruby-prof<span><a href="#label-ruby-prof">&para;</a> <a href="#top">&uarr;</a></span></h1>
+
+<p><a href="https://travis-ci.org/ruby-prof/ruby-prof"><img
+src="https://travis-ci.org/ruby-prof/ruby-prof.png?branch=master"
+alt="Build Status" /></a></p>
+
+<h2 id="label-Overview">Overview<span><a href="#label-Overview">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>ruby-prof is a fast code profiler for Ruby.  Its features include:</p>
+<ul><li>
+<p>Speed - it is a C extension and therefore many times faster than the
+standard Ruby profiler.</p>
+</li><li>
+<p>Modes - Ruby prof can measure a number of different parameters, including
+call times, memory usage and object allocations.</p>
+</li><li>
+<p>Reports - can generate text and cross-referenced html reports</p>
+<ul><li>
+<p>Flat Profiles - similar to the reports generated by the standard Ruby
+profiler</p>
+</li><li>
+<p>Graph profiles - similar to GProf, these show how long a method runs, which
+methods call it and which methods it calls.</p>
+</li><li>
+<p>Call tree profiles - outputs results in the calltree format suitable for
+the KCacheGrind profiling tool.</p>
+</li><li>
+<p>Many more – see reports section of this <a
+href="README_rdoc.html">README</a>.</p>
+</li></ul>
+</li><li>
+<p>Threads - supports profiling multiple threads simultaneously</p>
+</li></ul>
+
+<h2 id="label-Requirements">Requirements<span><a href="#label-Requirements">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>ruby-prof requires Ruby 1.9.3 or higher.</p>
+
+<p>If you are running Linux or Unix you&#39;ll need a C compiler so the
+extension can be compiled when it is installed.</p>
+
+<p>If you are running Windows, then you may need to install the Windows
+specific RubyGem which includes an already built extension (see Install
+section).</p>
+
+<h2 id="label-Install">Install<span><a href="#label-Install">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>The easiest way to install ruby-prof is by using Ruby Gems.  To install:</p>
+
+<pre class="ruby"><span class="ruby-identifier">gem</span> <span class="ruby-identifier">install</span> <span class="ruby-identifier">ruby</span><span class="ruby-operator">-</span><span class="ruby-identifier">prof</span>
+</pre>
+
+<p>If you&#39;re on windows then please install the devkit first so that it
+can compile.</p>
+
+<h2 id="label-Usage">Usage<span><a href="#label-Usage">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>There are two ways of running ruby-prof, via the command line or via its
+API.</p>
+
+<h3 id="label-ruby-prof+executable">ruby-prof executable<span><a href="#label-ruby-prof+executable">&para;</a> <a href="#top">&uarr;</a></span></h3>
+
+<p>The first is to use ruby-prof to run the Ruby program you want to profile.
+For more information refer to the documentation of the ruby-prof command.</p>
+
+<h3 id="label-ruby-prof+API">ruby-prof API<span><a href="#label-ruby-prof+API">&para;</a> <a href="#top">&uarr;</a></span></h3>
+
+<p>The second way is to use the ruby-prof API to profile particular segments
+of code.</p>
+
+<pre>require &#39;ruby-prof&#39;
+
+# Profile the code
+RubyProf.start
+...
+[code to profile]
+...
+result = RubyProf.stop
+
+# Print a flat profile to text
+printer = RubyProf::FlatPrinter.new(result)
+printer.print(STDOUT)</pre>
+
+<p>Alternatively, you can use a block to tell ruby-prof what to profile:</p>
+
+<pre>require &#39;ruby-prof&#39;
+
+# Profile the code
+result = RubyProf.profile do
+  ...
+  [code to profile]
+  ...
+end
+
+# Print a graph profile to text
+printer = RubyProf::GraphPrinter.new(result)
+printer.print(STDOUT, {})</pre>
+
+<p>ruby-prof also supports pausing and resuming profiling runs.</p>
+
+<pre>require &#39;ruby-prof&#39;
+
+# Profile the code
+RubyProf.start
+[code to profile]
+RubyProf.pause
+[other code]
+RubyProf.resume
+[code to profile]
+result = RubyProf.stop</pre>
+
+<p>Note that resume will automatically call start if a profiling run has not
+yet started.  In addition, resume can also take a block:</p>
+
+<pre>require &#39;ruby-prof&#39;
+
+# Profile the code
+RubyProf.resume do
+  [code to profile]
+end
+
+data = RubyProf.stop</pre>
+
+<p>With this usage, resume will automatically call pause at the end of the
+block.</p>
+
+<h2 id="label-Method+and+Thread+Elimination">Method and Thread Elimination<span><a href="#label-Method+and+Thread+Elimination">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>ruby-prof supports eliminating specific methods and threads from profiling
+results. This is useful for reducing connectivity in the call graph, making
+it easier to identify the source of performance problems when using a graph
+printer.</p>
+
+<p>For example, consider Integer#times: it&#39;s hardly ever useful to know
+how much time is spent in the method itself. We&#39;re much more interested
+in how much the passed in block contributes to the time spent in the method
+which contains the Integer#times call.</p>
+
+<p>Methods are eliminated from the collected data by calling
+`eliminate_methods!` on the profiling result, before submitting it to a
+printer.</p>
+
+<pre class="ruby"><span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
+<span class="ruby-identifier">result</span>.<span class="ruby-identifier">eliminate_methods!</span>([<span class="ruby-node">/Integer#times/</span>])
+</pre>
+
+<p>The argument given to `eliminate_methods!` is either an array of regular
+expressions, or the name of a file containing a list of regular expressions
+(line separated text).</p>
+
+<p>After eliminating methods the resulting profile will appear exactly as if
+those methods had been inlined at their call sites.</p>
+
+<p>In a similar manner, threads can be excluded so they are not profiled at
+all.  To do this, pass an array of threads to exclude to ruby-prof:</p>
+
+<pre class="ruby"><span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-identifier">exclude_threads</span> = [ <span class="ruby-identifier">thread2</span> ]
+<span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">start</span>
+</pre>
+
+<p>Note that the excluded threads must be specified <strong>before</strong>
+profiling.</p>
+
+<h2 id="label-Benchmarking+full+load+time+including+rubygems+startup+cost">Benchmarking full load time including rubygems startup cost<span><a href="#label-Benchmarking+full+load+time+including+rubygems+startup+cost">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>If you want to get a more accurate measurement of what takes all of a
+gem&#39;s bin/xxx command to load, you may want to also measure
+rubygems&#39; startup penalty. You can do this by calling into
+bin/ruby-prof directly, ex:</p>
+
+<p>$ gem which ruby-prof</p>
+
+<pre>g:/192/lib/ruby/gems/1.9.1/gems/ruby-prof-0.10.2/lib/ruby-prof.rb</pre>
+
+<p>now run it thus (substitute lib/ruby-prof.rb with bin/ruby-prof):</p>
+
+<p>$ ruby g:/192/lib/ruby/gems/1.9.1/gems/ruby-prof-0.10.2/bin/ruby-prof
+g:192binsome_installed_gem_command</p>
+
+<p>or</p>
+
+<p>$ ruby g:/192/lib/ruby/gems/1.9.1/gems/ruby-prof-0.10.2/bin/ruby-prof
+./some_file_that_does_a_require_rubygems_at_the_beginning.rb</p>
+
+<h2 id="label-Profiling+Rails">Profiling Rails<span><a href="#label-Profiling+Rails">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>To profile a Rails application it is vital to run it using production like
+settings (cache classes, cache view lookups, etc.).  Otherwise, Rail&#39;s
+dependency loading code will overwhelm any time spent in the application
+itself (our tests show that Rails dependency loading causes a roughly 6x
+slowdown).  The best way to do this is create a new Rails environment,
+profile.rb.</p>
+
+<p>So to profile Rails:</p>
+<ol><li>
+<p>Create a new profile.rb environment.  Make sure to turn on cache_classes
+and cache_template_loading.  Otherwise your profiling results will be
+overwhelemed by the time Rails spends loading required files.  You should
+likely turn off caching.</p>
+</li><li>
+<p>Add the ruby-prof to your gemfile:</p>
+
+<pre class="ruby"><span class="ruby-identifier">group</span> :<span class="ruby-identifier">profile</span> <span class="ruby-keyword">do</span>
+  <span class="ruby-identifier">gem</span> <span class="ruby-string">&#39;ruby-prof&#39;</span>
+<span class="ruby-keyword">end</span>
+</pre>
+</li><li>
+<p>Add the ruby prof rack adapter to your middleware stack.  One way to do
+this is by adding the following code to config.ru:</p>
+
+<pre class="ruby"><span class="ruby-keyword">if</span> <span class="ruby-constant">Rails</span>.<span class="ruby-identifier">env</span>.<span class="ruby-identifier">profile?</span>
+  <span class="ruby-identifier">use</span> <span class="ruby-constant">Rack</span><span class="ruby-operator">::</span><span class="ruby-constant">RubyProf</span>, :<span class="ruby-identifier">path</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&#39;/temp/profile&#39;</span>
+<span class="ruby-keyword">end</span>
+</pre>
+
+<p>The path is where you want profiling results to be stored.  By default the
+rack adapter will generate a html call graph report and flat text report.</p>
+</li><li>
+<p>Now make a request to your running server.  New profiling information will
+be generated for each request.  Note that each request will overwrite the
+profiling reports created by the previous request!</p>
+</li></ol>
+
+<h2 id="label-Reports">Reports<span><a href="#label-Reports">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>ruby-prof can generate a number of different reports:</p>
+<ul><li>
+<p>Flat Reports</p>
+</li><li>
+<p>Graph Reports</p>
+</li><li>
+<p>HTML Graph Reports</p>
+</li><li>
+<p>Call graphs</p>
+</li><li>
+<p>Call stack reports</p>
+</li><li>
+<p>More!</p>
+</li></ul>
+
+<p>Flat profiles show the overall time spent in each method. They are a good
+way of quickly identifying which methods take the most time. An example of
+a flat profile and an explanation can be found in <a
+href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/flat.txt">examples/flat.txt</a>.</p>
+
+<p>There are several varieties of these – run $ ruby-prof –help</p>
+
+<p>Graph profiles also show the overall time spent in each method. In
+addition, they also show which methods call the current method and which
+methods its calls.  Thus they are good for understanding how methods gets
+called and provide insight into the flow of your program. An example text
+graph profile is located at <a
+href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/graph.txt">examples/graph.txt</a>.</p>
+
+<p>HTML Graph profiles are the same as graph profiles, except output is
+generated in hyper-linked HTML. Since graph profiles can be quite large,
+the embedded links make it much easier to navigate the results. An example
+html graph profile is located at <a
+href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/graph.html">examples/graph.html</a>.</p>
+
+<p>Call graphs output results in the calltree profile format which is used by
+KCachegrind. Call graph support was generously donated by Carl Shimer. More
+information about the format can be found at the <a
+href="http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindCalltreeFormat">KCachegrind</a>
+site.</p>
+
+<p>Call stack reports produce a HTML visualization of the time spent in each
+execution path of the profiled code. An example can be found at <a
+href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/stack.html">examples/stack.html</a>.</p>
+
+<p>Another good example: [<a
+href="http://twitpic.com/28z94a">twitpic.com/28z94a</a>]</p>
+
+<p>Finally, there&#39;s a so called MultiPrinter which can generate several
+reports in one profiling run. See <a
+href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/multi.stack.html">examples/multi.stack.html</a>.</p>
+
+<p>There is also a graphviz .dot visualiser.</p>
+
+<h2 id="label-Printers">Printers<span><a href="#label-Printers">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>Reports are created by printers.  Supported printers include:</p>
+<ul><li>
+<p><a href="RubyProf/FlatPrinter.html">RubyProf::FlatPrinter</a> - Creates a
+flat report in text format</p>
+</li><li>
+<p><a
+href="RubyProf/FlatPrinterWithLineNumbers.html">RubyProf::FlatPrinterWithLineNumbers</a>
+- same as above but more verbose</p>
+</li><li>
+<p><a href="RubyProf/GraphPrinter.html">RubyProf::GraphPrinter</a> - Creates a
+call graph report in text format</p>
+</li><li>
+<p><a href="RubyProf/GraphHtmlPrinter.html">RubyProf::GraphHtmlPrinter</a> -
+Creates a call graph report in HTML (separate files per thread)</p>
+</li><li>
+<p><a href="RubyProf/DotPrinter.html">RubyProf::DotPrinter</a> - Creates a
+call graph report in GraphViz&#39;s DOT format which can be converted to an
+image</p>
+</li><li>
+<p><a href="RubyProf/CallTreePrinter.html">RubyProf::CallTreePrinter</a> -
+Creates a call tree report compatible with KCachegrind.</p>
+</li><li>
+<p><a href="RubyProf/CallStackPrinter.html">RubyProf::CallStackPrinter</a> -
+Creates a HTML visualization of the Ruby stack</p>
+</li><li>
+<p><a href="RubyProf/MultiPrinter.html">RubyProf::MultiPrinter</a> - Uses the
+other printers to create several reports in one profiling run</p>
+</li><li>
+<p>More!</p>
+</li></ul>
+
+<p>To use a printer:</p>
+
+<pre>...
+result = RubyProf.stop
+printer = RubyProf::GraphPrinter.new(result)
+printer.print(STDOUT, :min_percent =&gt; 2)</pre>
+
+<p>The first parameter is any writable IO object such as STDOUT or a file. The
+second parameter, specifies the minimum percentage a method must take to be
+printed.  Percentages should be specified as integers in the range 0 to
+100. For more information please see the documentation for the different
+printers.</p>
+
+<p>The other option is :print_file =&gt; true (default false), which adds the
+filename to the output (GraphPrinter only).</p>
+
+<p>The MultiPrinter differs from the other printers in that it requires a
+directory path and a basename for the files it produces.</p>
+
+<pre class="ruby"><span class="ruby-identifier">printer</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">MultiPrinter</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">result</span>)
+<span class="ruby-identifier">printer</span>.<span class="ruby-identifier">print</span>(:<span class="ruby-identifier">path</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;.&quot;</span>, :<span class="ruby-identifier">profile</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;profile&quot;</span>)
+</pre>
+
+<h2 id="label-Measurements">Measurements<span><a href="#label-Measurements">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>Depending on the mode and platform, ruby-prof can measure various aspects
+of a Ruby program.  Supported measurements include:</p>
+<ul><li>
+<p>wall time (RubyProf::WALL_TIME)</p>
+</li><li>
+<p>process time (RubyProf::PROCESS_TIME)</p>
+</li><li>
+<p>cpu time (RubyProf::CPU_TIME)</p>
+</li><li>
+<p>object allocations (RubyProf::ALLOCATIONS)</p>
+</li><li>
+<p>memory usage (RubyProf::MEMORY)</p>
+</li><li>
+<p>garbage collection time (RubyProf::GC_TIME)</p>
+</li><li>
+<p>garbage collections runs (RubyProf::GC_RUNS)</p>
+</li></ul>
+
+<p>Wall time measures the real-world time elapsed between any two moments. If
+there are other processes concurrently running on the system that use
+significant CPU or disk time during a profiling run then the reported
+results will be larger than expected.</p>
+
+<p>Process time measures the time used by a process between any two moments.
+It is unaffected by other processes concurrently running on the system.
+Note that Windows does not support measuring process times.</p>
+
+<p>CPU time uses the CPU clock counter to measure time.  The returned values
+are dependent on the correctly setting the CPU&#39;s frequency. This mode
+is only supported on Pentium or PowerPC platforms (linux only).</p>
+
+<p>Object allocation reports show how many objects each method in a program
+allocates.  This support was added by Sylvain Joyeux and requires a patched
+Ruby interpreter. See below.</p>
+
+<p>Memory usage reports show how much memory each method in a program uses. 
+This support was added by Alexander Dymo and requires a patched Ruby
+interpreter. See below.</p>
+
+<p>Garbage collection time reports how much time is spent in Ruby&#39;s
+garbage collector during a profiling session. This support was added by
+Jeremy Kemper and requires a patched Ruby interpreter. See below.</p>
+
+<p>Garbage collection runs report how many times Ruby&#39;s garbage collector
+is invoked during a profiling session. This support was added by Jeremy
+Kemper and requires a patched Ruby interpreter. See below.</p>
+
+<p>Ruby patches: all of the patches to Ruby are included in the railsexpress
+patchsets for rvm, see <a
+href="https://github.com/skaes/rvm-patchsets">github.com/skaes/rvm-patchsets</a></p>
+
+<p>To set the measurement:</p>
+<ul><li>
+<p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
+RubyProf::WALL_TIME</p>
+</li><li>
+<p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
+RubyProf::PROCESS_TIME</p>
+</li><li>
+<p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
+RubyProf::CPU_TIME</p>
+</li><li>
+<p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
+RubyProf::ALLOCATIONS</p>
+</li><li>
+<p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
+RubyProf::MEMORY</p>
+</li><li>
+<p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
+RubyProf::GC_TIME</p>
+</li><li>
+<p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
+RubyProf::GC_RUNS</p>
+</li></ul>
+
+<p>The default value is RubyProf::WALL_TIME.</p>
+
+<p>You may also specify the measure_mode by using the RUBY_PROF_MEASURE_MODE
+environment variable:</p>
+<ul><li>
+<p>export RUBY_PROF_MEASURE_MODE=wall</p>
+</li><li>
+<p>export RUBY_PROF_MEASURE_MODE=process</p>
+</li><li>
+<p>export RUBY_PROF_MEASURE_MODE=cpu</p>
+</li><li>
+<p>export RUBY_PROF_MEASURE_MODE=allocations</p>
+</li><li>
+<p>export RUBY_PROF_MEASURE_MODE=memory</p>
+</li><li>
+<p>export RUBY_PROF_MEASURE_MODE=gc_time</p>
+</li><li>
+<p>export RUBY_PROF_MEASURE_MODE=gc_runs</p>
+</li></ul>
+
+<p>On Linux, process time is measured using the clock method provided by the C
+runtime library. Note that the clock method does not report time spent in
+the kernel or child processes and therefore does not measure time spent in
+methods such as Kernel.sleep method. If you need to measure these values,
+then use wall time.  Wall time is measured using the gettimeofday kernel
+method.</p>
+
+<p>If you set the clock mode to PROCESS_TIME, then timings are read using the
+clock method provided by the C runtime library.  Note though, these values
+are wall times on Windows and not process times like on Linux.  Wall time
+is measured using the GetLocalTime API.</p>
+
+<p>If you use wall time, the results will be affected by other processes
+running on your computer, network delays, disk access, etc.  As result, for
+the best results, try to make sure your computer is only performing your
+profiling run and is otherwise quiescent.</p>
+
+<h2 id="label-Multi-threaded+Applications">Multi-threaded Applications<span><a href="#label-Multi-threaded+Applications">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>Unfortunately, Ruby does not provide an internal api for detecting thread
+context switches in 1.8.  As a result, the timings ruby-prof reports for
+each thread may be slightly inaccurate.  In particular, this will happen
+for newly spawned threads that go to sleep immediately (their first call).
+For instance, if you use Ruby&#39;s timeout library to wait for 2 seconds,
+the 2 seconds will be assigned to the foreground thread and not the newly
+created background thread.  These errors can largely be avoided if the
+background thread performs any operation before going to sleep.</p>
+
+<h2 id="label-Performance">Performance<span><a href="#label-Performance">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>Significant effort has been put into reducing ruby-prof&#39;s overhead as
+much as possible.  Our tests show that the overhead associated with
+profiling code varies considerably with the code being profiled.  Most
+programs will run approximately twice as slow while highly recursive
+programs (like the fibonacci series test) will run three times slower.</p>
+
+<h2 id="label-License">License<span><a href="#label-License">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>See <a href="LICENSE.html">LICENSE</a> for license information.</p>
+
+<h2 id="label-Development">Development<span><a href="#label-Development">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>Code is located at <a
+href="https://github.com/ruby-prof/ruby-prof">github.com/ruby-prof/ruby-prof</a></p>
+
+<p>Google group/mailing list: <a
+href="http://groups.google.com/group/ruby-optimization">groups.google.com/group/ruby-optimization</a>
+or start a github issue.</p>
+</main>
+
+
+
+<footer id="validator-badges" role="contentinfo">
+  <p><a href="http://validator.w3.org/check/referer">Validate</a>
+  <p>Generated by <a href="http://docs.seattlerb.org/rdoc/">RDoc</a> 4.2.0.
+  <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
+</footer>
+