ruby-prof 0.15.9 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 22ff7386396e7f34166a995b4f7a095d172544ef
-  data.tar.gz: caef497365c65eb46e411f511c9f19e30d5d9502
+  metadata.gz: 34157be7a5a12bf59f9a32a87772865ffdfcd4d5
+  data.tar.gz: b8e596d1691d4a7c06219fa565f3aa59d4c6c454
 SHA512:
-  metadata.gz: 09c37e34272db2c85851224b6ed454919797b3f6d9e9a2059272df0cbe09d4cbb1720b95683228c02966ad97927cf940c1a0c98a64fd77c684315b511915e528
-  data.tar.gz: 6b2aede7156ff82f4929b6d58e67febc869f933a8ef76948fbc785510e5bb350f69a9c0dbc523c5a4778a15f8de647efaa3f836d86d15939e37b857ad8c52bee
+  metadata.gz: 86b2dad68efbc23d8c20d76f030cc9261ad1a6db209319d4eb18e9ad840f7c8c85d4ea08f18dc0855970d8faecbff53ae71282ddf640e9b8840622985f318bc3
+  data.tar.gz: f68457fd69407d964b329937f4eb87459fdb1b7a0fffc4a8f64002d6600106bc916f60a73d7edfa2e4c335fb6b44d7a76844793c7ee3f586c837fc162abd9698

data/CHANGES

@@ -1,4 +1,30 @@
-0.16.0 (2015-12-08)
+0.16.0 (2016-08-24)
+=====================
+* ruby-prof can now be installed if ruby has been compiled with --disable-gems or
+  RUBYOPT includes --disable-gems (thx to Arthur Nogueira Neves)
+* Profile.new now accepts and prefers an options hash:
+  - measure_mode: one of the RubyProf measure mode constants
+  - exclude_threads: an array of threads to ignore when collecting profile data
+  - include_threads: an array of threads to include when collecting profile data
+  - merge_fibers: whether or not to merge the profile data for all fibers under their creating thread
+* overhauled printer for cachegrind profiles:
+  - profile data for each thread dumped to a separate file, as kcachegrind does not
+    fully implement the cachegrind specification
+  - this required a change in interface: it's now necessary to specify a directory
+    where to dump the cachegrind files
+  - naming convention for cachegrind files changed so that kcachegrind shows them
+    all in the open dialog
+* improved Rack middleware:
+  - it's now possible to use the MultiPrinter
+  - new option ignore_existing_threads: will ignore all prexisiting threads
+    when profiling a request, except the thread perfoming the request.
+  - new option request_thread_only: will ignore all preexisting threads, but also
+    all threads spwaned during the execution of the rack request.
+  - new option merge_fibers: whether or not to merge the profile data for all fibers under their creating thread
+* fixed setting threshold bug when displaying stack profiles (thx to Michal Konarski)
+* code related to printing profiles is now autoloaded for efficiency (thx to Dave Gynn)
+
+0.15.9 (2015-12-08)
 ======================
 * rack profiler now supports lambdas for generating profile paths (thx to Jean Rougé)
 * fixed a bug when printing graph profiles

data/README.rdoc

@@ -21,7 +21,7 @@ ruby-prof requires Ruby 1.9.3 or higher. Please note some ruby
 releases have known bugs which cause ruby-prof problems, like
 incorrect measurements. We suggest to use the latest minor patch level
 release if possible. In particular, on the 2.1 branch of ruby you
-should use 2.1.7.
+should use at least 2.1.7.
 
 If you are running Linux or Unix you'll need a C compiler so the
 extension can be compiled when it is installed.
@@ -41,20 +41,20 @@ can compile.
 
 == Usage
 
-There are two ways of running ruby-prof, via the command line or via
-its API.
+There are three major options for running ruby-prof: via the command
+line, via its convenience API or via its core API.
 
-=== ruby-prof executable
+=== ruby-prof Executable
 
 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
+profile.  For more information refer to the documentation of the
 ruby-prof command.
 
 
-=== ruby-prof API
+=== ruby-prof Convenience API
 
-The second way is to use the ruby-prof API to profile particular
-segments of code.
+The second way is to use the ruby-prof convenience API to profile
+particular segments of code.
 
     require 'ruby-prof'
 
@@ -95,8 +95,8 @@ ruby-prof also supports pausing and resuming profiling runs.
     # ... code to profile ...
     result = RubyProf.stop
 
-Note that resume will automatically call start if a profiling run
-has not yet started.  In addition, resume can also take a block:
+Note that resume will only work if start has been called previously.
+In addition, resume can also take a block:
 
     require 'ruby-prof'
 
@@ -104,13 +104,56 @@ has not yet started.  In addition, resume can also take a block:
       # ... code to profile...
     end
 
-    data = RubyProf.stop
+    result = RubyProf.stop
 
 With this usage, resume will automatically call pause at the
 end of the block.
 
+=== Profiling Selected Threads (Core API)
+
+The convenience API does not support running multiple profiles in
+separate threads concurrently, but the RubyProf::Profile API does. In
+fact, the convenience layer uses the Profile API internally. It all
+revolves around Profile objects:
+
+RubyProf::Profile.new::
+   Create a profile object given an options hash (see below)
+
+   The following options are available when creating Profile instances:
+
+   measure_mode::
+       One of the defined measure modes
+
+   exclude_threads::
+       Array of threads which should not be profiled.
+
+   include_threads::
+       Array of threads which should be profiled. All other threads will
+       be ignored.
+
+   merge_fibers::
+       Whether profiling data for a given thread's fibers should all be
+       subsumed under a single entry. Basically only useful to produce
+       callgrind profiles.
+
+RubyProf::Profile#start::
+   Start profiling
+
+RubyProf::Profile#pause::
+   Pause profiling
+
+RubyProf::Profile#resume::
+   Resume profiling
+
+RubyProf::Profile#stop::
+   Stop profiling and return self
 
-== Method and Thread Elimination
+RubyProf::Profile#profile::
+   Perform a profile run and return result. Accepts the same arguments
+   as RubyProf::Profile.new.
+
+
+== Method Elimination
 
 ruby-prof supports eliminating specific methods and threads from
 profiling results. This is useful for reducing connectivity in the
@@ -136,13 +179,6 @@ regular expressions (line separated text).
 After eliminating methods the resulting profile will appear exactly as if those methods
 had been inlined at their call sites.
 
-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:
-
-    RubyProf::exclude_threads = [ thread2 ]
-    RubyProf.start
-
-Note that the excluded threads must be specified *before* profiling.
 
 == Profiling Rails
 
@@ -158,7 +194,7 @@ So to profile Rails:
 1. Create a new profile.rb environment. Make sure to turn on
    <tt>cache_classes</tt> and
    <tt>cache_template_loading</tt>. Otherwise your profiling results
-   will be overwhelemed by the time Rails spends loading required
+   will be overwhelmed by the time Rails spends loading required
    files. You should likely turn off caching.
 
 2. Add the ruby-prof to your gemfile:
@@ -325,8 +361,17 @@ RubyProf::GC_RUNS::
  is invoked during a profiling session. This support was added by
  Jeremy Kemper and requires a patched Ruby interpreter. See below.
 
+== Patching ruby
+
 All of the patches to Ruby are included in the railsexpress patchsets
-for rvm, see https://github.com/skaes/rvm-patchsets
+for rvm, see https://github.com/skaes/rvm-patchsets. You can also use
+these patches manually with other ruby managers (ruby-install, 
+ruby-build, etc.).
+
+Note if you rebuild your ruby with patches you must uninstall and
+reinstall the ruby-prof gem to take advantage of the new capabilities.
+
+== Measure modes
 
 To set the measurement:
 
@@ -371,16 +416,15 @@ otherwise quiescent.
 
 == Multi-threaded Applications
 
-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'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.
+Unfortunately, Ruby does not provide an internal API for detecting
+thread context switches.  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'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.
 
 == Performance
 
@@ -395,6 +439,14 @@ will run three times slower.
 
 See LICENSE for license information.
 
+== API Documentation
+
+The ruby-prof API documentation for the latest released gem version
+can be found here: http://www.rubydoc.info/gems/ruby-prof/
+
+The ruby-prof API documentation for the master branch is available
+here: http://www.rubydoc.info/github/ruby-prof/ruby-prof/
+
 == Development
 
 Code is located at https://github.com/ruby-prof/ruby-prof

data/bin/ruby-prof

@@ -102,8 +102,8 @@ module RubyProf
         opts.on('--mode=measure_mode',
                 [:process, :wall, :cpu, :allocations, :memory, :gc_runs, :gc_time],
                 'Select what ruby-prof should measure:',
-                '  process - Process time (default).',
-                '  wall - Wall time.',
+                '  wall - Wall time (default).',
+                '  process - Process time.',
                 '  cpu - CPU time (Pentium and PowerPCs only).',
                 '  allocations - Object allocations (requires patched Ruby interpreter).',
                 '  memory - Allocated memory in KB (requires patched Ruby interpreter).',
@@ -111,10 +111,10 @@ module RubyProf
                 '  gc_time - Time spent in garbage collection (requires patched Ruby interpreter).') do |measure_mode|
 
           case measure_mode
-          when :process
-            options.measure_mode = RubyProf::PROCESS_TIME
           when :wall
             options.measure_mode = RubyProf::WALL_TIME
+          when :process
+            options.measure_mode = RubyProf::PROCESS_TIME
           when :cpu
             options.measure_mode = RubyProf::CPU_TIME
           when :allocations

data/doc/LICENSE.html

@@ -108,7 +108,7 @@ DAMAGE.</p>
 
 <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>Generated by <a href="http://docs.seattlerb.org/rdoc/">RDoc</a> 4.2.2.
   <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

@@ -60,16 +60,20 @@
     <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-ruby-prof+Executable">ruby-prof Executable</a>
+    <li><a href="#label-ruby-prof+Convenience+API">ruby-prof Convenience API</a>
+    <li><a href="#label-Profiling+Selected+Threads+-28Core+API-29">Profiling Selected Threads (Core API)</a>
+    <li><a href="#label-Method+Elimination">Method Elimination</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-Patching+ruby">Patching ruby</a>
+    <li><a href="#label-Measure+modes">Measure modes</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-API+Documentation">API Documentation</a>
     <li><a href="#label-Development">Development</a>
   </ul>
 </div>
@@ -137,7 +141,8 @@ the KCacheGrind profiling tool.</p>
 <p>ruby-prof requires Ruby 1.9.3 or higher. Please note some ruby releases
 have known bugs which cause ruby-prof problems, like incorrect
 measurements. We suggest to use the latest minor patch level release if
-possible. In particular, on the 2.1 branch of ruby you should use 2.1.7.</p>
+possible. In particular, on the 2.1 branch of ruby you should use at least
+2.1.7.</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>
@@ -158,18 +163,18 @@ 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>
+<p>There are three major options for running ruby-prof: via the command line,
+via its convenience API or via its core 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>
+<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.
+<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>
+<h3 id="label-ruby-prof+Convenience+API">ruby-prof Convenience API<span><a href="#label-ruby-prof+Convenience+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>
+<p>The second way is to use the ruby-prof convenience API to profile
+particular segments of code.</p>
 
 <pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;ruby-prof&#39;</span>
 
@@ -213,8 +218,8 @@ of code.</p>
 <span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
 </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>
+<p>Note that resume will only work if start has been called previously. In
+addition, resume can also take a block:</p>
 
 <pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;ruby-prof&#39;</span>
 
@@ -222,13 +227,59 @@ yet started.  In addition, resume can also take a block:</p>
   <span class="ruby-comment"># ... code to profile...</span>
 <span class="ruby-keyword">end</span>
 
-<span class="ruby-identifier">data</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
+<span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
 </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>
+<h3 id="label-Profiling+Selected+Threads+-28Core+API-29">Profiling Selected Threads (Core API)<span><a href="#label-Profiling+Selected+Threads+-28Core+API-29">&para;</a> <a href="#top">&uarr;</a></span></h3>
+
+<p>The convenience API does not support running multiple profiles in separate
+threads concurrently, but the <a
+href="RubyProf/Profile.html">RubyProf::Profile</a> API does. In fact, the
+convenience layer uses the Profile API internally. It all revolves around
+Profile objects:</p>
+<dl class="rdoc-list note-list"><dt><a href="RubyProf/Profile.html#method-c-new">RubyProf::Profile.new</a>
+<dd>
+<p>Create a profile object given an options hash (see below)</p>
+
+<p>The following options are available when creating Profile instances:</p>
+<dl class="rdoc-list note-list"><dt>measure_mode
+<dd>
+<p>One of the defined measure modes</p>
+</dd><dt>exclude_threads
+<dd>
+<p>Array of threads which should not be profiled.</p>
+</dd><dt>include_threads
+<dd>
+<p>Array of threads which should be profiled. All other threads will be
+ignored.</p>
+</dd><dt>merge_fibers
+<dd>
+<p>Whether profiling data for a given thread&#39;s fibers should all be
+subsumed under a single entry. Basically only useful to produce callgrind
+profiles.</p>
+</dd></dl>
+</dd><dt><a href="RubyProf/Profile.html#method-i-start">RubyProf::Profile#start</a>
+<dd>
+<p>Start profiling</p>
+</dd><dt><a href="RubyProf/Profile.html#method-i-pause">RubyProf::Profile#pause</a>
+<dd>
+<p>Pause profiling</p>
+</dd><dt><a href="RubyProf/Profile.html#method-i-resume">RubyProf::Profile#resume</a>
+<dd>
+<p>Resume profiling</p>
+</dd><dt><a href="RubyProf/Profile.html#method-i-stop">RubyProf::Profile#stop</a>
+<dd>
+<p>Stop profiling and return self</p>
+</dd><dt>RubyProf::Profile#profile
+<dd>
+<p>Perform a profile run and return result. Accepts the same arguments as <a
+href="RubyProf/Profile.html#method-c-new">RubyProf::Profile.new</a>.</p>
+</dd></dl>
+
+<h2 id="label-Method+Elimination">Method Elimination<span><a href="#label-Method+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
@@ -255,16 +306,6 @@ 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-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
@@ -278,7 +319,7 @@ profile.rb.</p>
 <ol><li>
 <p>Create a new profile.rb environment. Make sure to turn on
 <code>cache_classes</code> and <code>cache_template_loading</code>.
-Otherwise your profiling results will be overwhelemed by the time Rails
+Otherwise your profiling results will be overwhelmed 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>
@@ -455,9 +496,18 @@ is invoked during a profiling session. This support was added by Jeremy
 Kemper and requires a patched Ruby interpreter. See below.</p>
 </dd></dl>
 
+<h2 id="label-Patching+ruby">Patching ruby<span><a href="#label-Patching+ruby">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
 <p>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>
+href="https://github.com/skaes/rvm-patchsets">github.com/skaes/rvm-patchsets</a>.
+You can also use these patches manually with other ruby managers
+(ruby-install,  ruby-build, etc.).</p>
+
+<p>Note if you rebuild your ruby with patches you must uninstall and reinstall
+the ruby-prof gem to take advantage of the new capabilities.</p>
+
+<h2 id="label-Measure+modes">Measure modes<span><a href="#label-Measure+modes">&para;</a> <a href="#top">&uarr;</a></span></h2>
 
 <p>To set the measurement:</p>
 
@@ -504,11 +554,11 @@ 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
+context switches.  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>
 
@@ -524,6 +574,15 @@ programs (like the fibonacci series test) will run three times slower.</p>
 
 <p>See <a href="LICENSE.html">LICENSE</a> for license information.</p>
 
+<h2 id="label-API+Documentation">API Documentation<span><a href="#label-API+Documentation">&para;</a> <a href="#top">&uarr;</a></span></h2>
+
+<p>The ruby-prof API documentation for the latest released gem version can be
+found here: <a
+href="http://www.rubydoc.info/gems/ruby-prof">www.rubydoc.info/gems/ruby-prof</a>/</p>
+
+<p>The ruby-prof API documentation for the master branch is available here: <a
+href="http://www.rubydoc.info/github/ruby-prof/ruby-prof">www.rubydoc.info/github/ruby-prof/ruby-prof</a>/</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
@@ -538,7 +597,7 @@ or open a github issue.</p>
 
 <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>Generated by <a href="http://docs.seattlerb.org/rdoc/">RDoc</a> 4.2.2.
   <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
 </footer>