RubyGems - ruby-prof - Versions diffs - 0.4.0 - Mend

ruby-prof 0.4.0

Files changed (56) hide show

data/CHANGES +17 -0
data/LICENSE +23 -0
data/README +220 -0
data/Rakefile +141 -0
data/bin/ruby-prof +154 -0
data/doc/classes/RubyProf.html +563 -0
data/doc/classes/RubyProf/CallInfo.html +274 -0
data/doc/classes/RubyProf/FlatPrinter.html +207 -0
data/doc/classes/RubyProf/GraphHtmlPrinter.html +538 -0
data/doc/classes/RubyProf/GraphPrinter.html +240 -0
data/doc/classes/RubyProf/MethodInfo.html +556 -0
data/doc/classes/RubyProf/ProfileTask.html +395 -0
data/doc/classes/RubyProf/Result.html +234 -0
data/doc/created.rid +1 -0
data/doc/files/LICENSE.html +142 -0
data/doc/files/README.html +376 -0
data/doc/files/bin/ruby-prof.html +143 -0
data/doc/files/examples/flat_txt.html +187 -0
data/doc/files/examples/graph_html.html +948 -0
data/doc/files/examples/graph_txt.html +305 -0
data/doc/files/ext/ruby_prof_c.html +101 -0
data/doc/files/lib/ruby-prof/flat_printer_rb.html +101 -0
data/doc/files/lib/ruby-prof/graph_html_printer_rb.html +108 -0
data/doc/files/lib/ruby-prof/graph_printer_rb.html +101 -0
data/doc/files/lib/ruby-prof/profiletask_rb.html +109 -0
data/doc/files/lib/ruby-prof_rb.html +111 -0
data/doc/files/lib/unprof_rb.html +108 -0
data/doc/fr_class_index.html +34 -0
data/doc/fr_file_index.html +39 -0
data/doc/fr_method_index.html +67 -0
data/doc/index.html +24 -0
data/doc/rdoc-style.css +208 -0
data/examples/flat.txt +57 -0
data/examples/graph.html +827 -0
data/examples/graph.txt +171 -0
data/ext/extconf.rb +19 -0
data/ext/ruby_prof.c +1433 -0
data/lib/ruby-prof.rb +38 -0
data/lib/ruby-prof/flat_printer.rb +76 -0
data/lib/ruby-prof/graph_html_printer.rb +227 -0
data/lib/ruby-prof/graph_printer.rb +142 -0
data/lib/ruby-prof/profiletask.rb +150 -0
data/lib/unprof.rb +8 -0
data/test/basic_test.rb +141 -0
data/test/clock_mode_test.rb +73 -0
data/test/module_test.rb +45 -0
data/test/prime.rb +58 -0
data/test/prime_test.rb +24 -0
data/test/printers_test.rb +28 -0
data/test/recursive_test.rb +55 -0
data/test/test.rb +3 -0
data/test/test_helper.rb +45 -0
data/test/test_suite.rb +9 -0
data/test/thread_test.rb +32 -0
data/test/timing_test.rb +90 -0
metadata +121 -0

data/doc/created.rid ADDED Viewed

	@@ -0,0 +1 @@
1	+ Wed Jun 21 01:45:05 Mountain Standard Time 2006

data/doc/files/LICENSE.html ADDED Viewed

@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html
+     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>File: LICENSE</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <meta http-equiv="Content-Script-Type" content="text/javascript" />
+  <link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
+  <script type="text/javascript">
+  // <![CDATA[
+  function popupCode( url ) {
+    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+  }
+  function toggleCode( id ) {
+    if ( document.getElementById )
+      elem = document.getElementById( id );
+    else if ( document.all )
+      elem = eval( "document.all." + id );
+    else
+      return false;
+    elemStyle = elem.style;
+    if ( elemStyle.display != "block" ) {
+      elemStyle.display = "block"
+    } else {
+      elemStyle.display = "none"
+    }
+    return true;
+  }
+  // Make codeblocks hidden by default
+  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
+  // ]]>
+  </script>
+</head>
+<body>
+  <div id="fileHeader">
+    <h1>LICENSE</h1>
+    <table class="header-table">
+    <tr class="top-aligned-row">
+      <td><strong>Path:</strong></td>
+      <td>LICENSE
+      </td>
+    </tr>
+    <tr class="top-aligned-row">
+      <td><strong>Last Update:</strong></td>
+      <td>Sat Jun 17 04:03:12 Mountain Standard Time 2006</td>
+    </tr>
+    </table>
+  </div>
+  <!-- banner header -->
+  <div id="bodyContent">
+  <div id="contextContent">
+    <div id="description">
+      <p>
+Copyright (C) 2005 Shugo Maeda &lt;shugo@ruby-lang.org&gt; All rights
+reserved.
+</p>
+<pre>
+ *
+</pre>
+<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>Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+</li>
+<li>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.
+</li>
+</ol>
+<pre>
+ *
+</pre>
+<p>
+THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS
+IS&#8217;&#8217; 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>
+    </div>
+   </div>
+  </div>
+    <!-- if includes -->
+    <div id="section">
+    <!-- if method_list -->
+  </div>
+<div id="validator-badges">
+  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+</div>
+</body>
+</html>

data/doc/files/README.html ADDED Viewed

@@ -0,0 +1,376 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html
+     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <title>File: README</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <meta http-equiv="Content-Script-Type" content="text/javascript" />
+  <link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
+  <script type="text/javascript">
+  // <![CDATA[
+  function popupCode( url ) {
+    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
+  }
+  function toggleCode( id ) {
+    if ( document.getElementById )
+      elem = document.getElementById( id );
+    else if ( document.all )
+      elem = eval( "document.all." + id );
+    else
+      return false;
+    elemStyle = elem.style;
+    if ( elemStyle.display != "block" ) {
+      elemStyle.display = "block"
+    } else {
+      elemStyle.display = "none"
+    }
+    return true;
+  }
+  // Make codeblocks hidden by default
+  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
+  // ]]>
+  </script>
+</head>
+<body>
+  <div id="fileHeader">
+    <h1>README</h1>
+    <table class="header-table">
+    <tr class="top-aligned-row">
+      <td><strong>Path:</strong></td>
+      <td>README
+      </td>
+    </tr>
+    <tr class="top-aligned-row">
+      <td><strong>Last Update:</strong></td>
+      <td>Tue Jun 20 23:21:24 Mountain Standard Time 2006</td>
+    </tr>
+    </table>
+  </div>
+  <!-- banner header -->
+  <div id="bodyContent">
+  <div id="contextContent">
+    <div id="description">
+      <h1>ruby-prof</h1>
+<h2>Overview</h2>
+<p>
+ruby-prof is a fast code profiler for Ruby. Its features include:
+</p>
+<ul>
+<li>Speed - it is a C extension and therefore many times faster than the
+standard Ruby profiler.
+</li>
+<li>Flat Profiles - similar to the reports generated by the standard Ruby
+profiler
+</li>
+<li>Graph profiles - similar to GProf, these show how long a method runs, which
+methods call it and which methods it calls.
+</li>
+<li>Threads - supports profiling multiple threads simultaneously
+</li>
+<li>Recursive calls - supports profiling recursive method calls
+</li>
+<li>Reports - can generate both text and cross-referenced html reports
+</li>
+<li>Output - can output to standard out or to a file
+</li>
+</ul>
+<h2>Requirements</h2>
+<p>
+ruby-prof requires Ruby 1.8.2 or higher.
+</p>
+<p>
+If you are running Linux or Unix you&#8217;ll need a C compiler so the
+extension can be compiled when it is installed.
+</p>
+<p>
+If you are running Windows, then install the Windows specific RubyGem which
+includes an already built extension.
+</p>
+<h2>Install</h2>
+<p>
+ruby-prof is provided as a RubyGem. To install:
+</p>
+<p>
+<tt>gem install ruby-prof</tt>
+</p>
+<p>
+If you are running Windows, make sure to install the Win32 RubyGem which
+includes a pre-built binary.
+</p>
+<h2>Usage</h2>
+<p>
+There are three ways of running ruby-prof.
+</p>
+<h3>ruby-prof executable</h3>
+<p>
+The first is to use ruby-prof to run the Ruby program you want to profile.
+For more information refer to the ruby-prof <a
+href="bin/ruby-prof.html">documentation</a>.
+</p>
+<h3>ruby-prof API</h3>
+<p>
+The second way is to use the ruby-prof API to profile particular segments
+of code.
+</p>
+<pre>
+  require 'ruby-prof'
+  # Profile the code
+  RubyProf.start
+  ...
+  [code to profile]
+  ...
+  result = RubyProf.end
+  # Print a flat profile to text
+  printer = RubyProf::TextPrinter.new(result)
+  printer.print(STDOUT, 0)
+</pre>
+<p>
+Alternatively, you can use a block to tell ruby-prof what to profile:
+</p>
+<pre>
+  require 'ruby-prof'
+  # 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, 0)
+</pre>
+<h3>require unprof</h3>
+<p>
+The third way of using ruby-prof is by requiring unprof.rb:
+</p>
+<pre>
+        require 'unprof'
+</pre>
+<p>
+This will start profiling immediately and will output the results using a
+flat profile report.
+</p>
+<p>
+This method is provided for backwards compatibility. Using <a
+href="bin/ruby-prof.html">ruby-prof</a> provides more flexibility.
+</p>
+<h2>Reports</h2>
+<p>
+ruby-prof can generate flat profile and graph profile reports.
+</p>
+<p>
+Flat profiles show the overall time spent in each method. They are a good
+of quickly identifying which methods take the most time. An example of a
+flat profile and an explanation can be found in <a
+href="examples/flat_txt.html">examples/flat.txt</a>.
+</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. Graph profiles
+can be generated in text and html. Since the html is cross-referenced it is
+easier to work with. An example text graph profile is located at <a
+href="examples/graph_txt.html">examples/graph.txt</a> while an example html
+graph file is located at <a
+href="examples/graph_html.html">examples/graph.html</a>.
+</p>
+<p>
+Reports are created by printers. The current printers include:
+</p>
+<ul>
+<li><a href="../classes/RubyProf/FlatPrinter.html">RubyProf::FlatPrinter</a> -
+Creates a flat report in text format
+</li>
+<li><a href="../classes/RubyProf/GraphPrinter.html">RubyProf::GraphPrinter</a>
+- Creates a call graph report in text format
+</li>
+<li><a
+href="../classes/RubyProf/GraphHtmlPrinter.html">RubyProf::GraphHtmlPrinter</a>
+- Creates a call graph report in HTML (separate files per thread)
+</li>
+</ul>
+<p>
+To use a printer:
+</p>
+<pre>
+  result = RubyProf.end
+  printer = RubyProf::GraphPrinter.new(result)
+  printer.print(STDOUT, 0)
+</pre>
+<p>
+The first parameter is any writable IO object such as STDOUT or a file. The
+second parameter, which has a default value of 0, specifies the minimum
+percentage a method must take to be printed. For more information please
+see the documentation for the different printers.
+</p>
+<h2>Timing Data</h2>
+<p>
+Depending on the mode and platform, ruby-prof can measure time in three
+ways - process time, wall time and cpu time.
+</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 - therefore, all
+measurements on Windows use wall time.
+</p>
+<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 too large.
+</p>
+<p>
+CPU time uses the CPU clock counter to measure time. The returned values
+are dependent on the correctly setting the CPU&#8217;s frequency. This mode
+is only supported on Pentium or PowerPC platforms.
+</p>
+<p>
+To set the clock_mode:
+</p>
+<pre>
+        RubyProf.clock_mode = RubyProf::PROCESS_TIME
+        RubyProf.clock_mode = RubyProf::WALL_TIME
+        RubyProf.clock_mode = RubyProf::CPU_TIME
+</pre>
+<p>
+This default value is PROCESS_TIME.
+</p>
+<p>
+You may also specify the clock_mode by using the RUBY_PROF_CLOCK_MODE
+environment variable:
+</p>
+<pre>
+        export RUBY_PROF_CLOCK_MODE=process
+        export RUBY_PROF_CLOCK_MODE=wall
+        export RUBY_PROF_CLOCK_MODE=cpu
+</pre>
+<p>
+Note that these values have changed since ruby-prof-0.3.0.
+</p>
+<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>
+On Windows, timings are always wall times. If you set the clock mode to
+PROCESS_TIME, then timing 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>
+On both platforms, cpu time is measured using the RDTSC assembly function
+provided by the Pentium and PowerPC platforms. CPU time is dependent on the
+cpu&#8217;s frequency. On Linux, ruby-prof attempts to read this value from
+&quot;/proc/cpuinfo.&quot; On Windows, you must specify the clock
+frequency. This can be done using the RUBY_PROF_CPU_FREQUENCY environment
+variable:
+</p>
+<pre>
+        export RUBY_PROF_CPU_FREQUENCY=&lt;value&gt;
+</pre>
+<p>
+You can also directly set the cpu frequency by calling:
+</p>
+<pre>
+        RubyProf.cpu_frequency = &lt;value&gt;
+</pre>
+<h2>Recursive Calls</h2>
+<p>
+Recursive calls occur when method A calls method A and cycles occur when
+method A calls method B calls method C calls method A. ruby-prof can detect
+recursive calls any cycle calls, but does not currently report these in its
+output.
+</p>
+<p>
+However, the self time values for recursive calls should always be
+accurate. It is also believed that the total times are accurate, but these
+should be carefully analyzed to verify their veracity.
+</p>
+<h2>Performance</h2>
+<p>
+Significant effort has been put into reducing ruby-prof&#8217;s overhead as
+much as possible. Our tests show that the overhead associated with
+profiling code varies considerably with the code being profiled. On the low
+end overhead is around 10% while on the high end its can around 80%.
+</p>
+<h2>Windows Binary</h2>
+<p>
+The Windows binary is built with the latest version of MinGW.
+</p>
+<h2>License</h2>
+<p>
+See LICENSE for license information.
+</p>
+    </div>
+   </div>
+  </div>
+    <!-- if includes -->
+    <div id="section">
+    <!-- if method_list -->
+  </div>
+<div id="validator-badges">
+  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+</div>
+</body>
+</html>