ruby-prof 0.15.8 → 0.15.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 37b855253c996f890816f330170e544cc3961679
-  data.tar.gz: 412f280dd5407c7005da0af110ed87d0f25cd56f
+  metadata.gz: 22ff7386396e7f34166a995b4f7a095d172544ef
+  data.tar.gz: caef497365c65eb46e411f511c9f19e30d5d9502
 SHA512:
-  metadata.gz: 8135b2e9722ba2a3cba8af88efc3618ffad734478570daa84a792f5bb768cac73b27ea1c6a4437b960459c5200fba7d78e28e6bedf85c9a258dfd178e8077762
-  data.tar.gz: 0dd3165ec04d338686a3acc9454f9b08f2fd3a97b14aaff26cd35ef75a82f50c9ec3fe1973c9cd143c67f50f853294f935b438f08d8786cd55f71497104b2b55
+  metadata.gz: 09c37e34272db2c85851224b6ed454919797b3f6d9e9a2059272df0cbe09d4cbb1720b95683228c02966ad97927cf940c1a0c98a64fd77c684315b511915e528
+  data.tar.gz: 6b2aede7156ff82f4929b6d58e67febc869f933a8ef76948fbc785510e5bb350f69a9c0dbc523c5a4778a15f8de647efaa3f836d86d15939e37b857ad8c52bee

data/CHANGES

@@ -1,3 +1,8 @@
+0.16.0 (2015-12-08)
+======================
+* rack profiler now supports lambdas for generating profile paths (thx to Jean Rougé)
+* fixed a bug when printing graph profiles
+
 0.15.8 (2015-04-24)
 ======================
 * added missing assets to gem build

data/README.rdoc

@@ -1,9 +1,10 @@
 = ruby-prof
+
 {<img src="https://travis-ci.org/ruby-prof/ruby-prof.png?branch=master" alt="Build Status" />}[https://travis-ci.org/ruby-prof/ruby-prof]
 
 == Overview
 
-ruby-prof is a fast code profiler for Ruby.  Its features include:
+ruby-prof is a fast code profiler for MRI Ruby.  Its features include:
 
 * Speed - it is a C extension and therefore many times faster than the standard Ruby profiler.
 * Modes - Ruby prof can measure a number of different parameters, including call times, memory usage and object allocations.
@@ -11,7 +12,7 @@ ruby-prof is a fast code profiler for Ruby.  Its features include:
   - Flat Profiles - similar to the reports generated by the standard Ruby profiler
   - Graph profiles - similar to GProf, these show how long a method runs, which methods call it and which methods it calls.
   - Call tree profiles - outputs results in the calltree format suitable for the KCacheGrind profiling tool.
-  - Many more -- see reports section of this README.
+  - Many more -- see reports section of this \README.
 * Threads - supports profiling multiple threads simultaneously
 
 == Requirements
@@ -20,25 +21,28 @@ 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.5.
+should use 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.
+If you are running Linux or Unix you'll need a C compiler so the
+extension can be compiled when it is installed.
 
 If you are running Windows, then you may need to install the
 Windows specific RubyGem which includes an already built extension (see Install section).
 
 == Install
 
-The easiest way to install ruby-prof is by using Ruby Gems.  To install:
+The easiest way to install ruby-prof is by using Ruby Gems.  To
+install:
 
-  gem install ruby-prof
+    gem install ruby-prof
 
-If you're on windows then please install the devkit first so that it can compile.
+If you're on windows then please install the devkit first so that it
+can compile.
 
 == Usage
 
-There are two ways of running ruby-prof, via the command line or via its API.
+There are two ways of running ruby-prof, via the command line or via
+its API.
 
 === ruby-prof executable
 
@@ -49,62 +53,58 @@ ruby-prof command.
 
 === ruby-prof 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 API to profile particular
+segments of code.
 
-  require 'ruby-prof'
+    require 'ruby-prof'
 
-  # Profile the code
-  RubyProf.start
-  ...
-  [code to profile]
-  ...
-  result = RubyProf.stop
+    # 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)
+    # print a flat profile to text
+    printer = RubyProf::FlatPrinter.new(result)
+    printer.print(STDOUT)
 
-Alternatively, you can use a block to tell ruby-prof what
-to profile:
+Alternatively, you can use a block to tell ruby-prof what to profile:
 
-  require 'ruby-prof'
+    require 'ruby-prof'
 
-  # Profile the code
-  result = RubyProf.profile do
-    ...
-    [code to profile]
-    ...
-  end
+    # 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, {})
+    # print a graph profile to text
+    printer = RubyProf::GraphPrinter.new(result)
+    printer.print(STDOUT, {})
 
 ruby-prof also supports pausing and resuming profiling runs.
 
-  require 'ruby-prof'
+    require 'ruby-prof'
+
+    # profile the code
+    RubyProf.start
+    # ... code to profile ...
+
+    RubyProf.pause
+    # ... other code ...
 
-  # Profile the code
-  RubyProf.start
-  [code to profile]
-  RubyProf.pause
-  [other code]
-  RubyProf.resume
-  [code to profile]
-  result = RubyProf.stop
+    RubyProf.resume
+    # ... 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:
 
-  require 'ruby-prof'
+    require 'ruby-prof'
 
-  # Profile the code
-  RubyProf.resume do
-    [code to profile]
-  end
+    RubyProf.resume do
+      # ... code to profile...
+    end
 
-  data = RubyProf.stop
+    data = RubyProf.stop
 
 With this usage, resume will automatically call pause at the
 end of the block.
@@ -112,22 +112,26 @@ end of the block.
 
 == Method and Thread Elimination
 
-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.
+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.
 
-For example, consider Integer#times: it's hardly ever useful to know how much time is
-spent in the method itself. We'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.
+For example, consider <tt>Integer#times</tt>: it's hardly ever useful
+to know how much time is spent in the method itself. We're much more
+interested in how much the passed in block contributes to the time
+spent in the method which contains the <tt>Integer#times</tt> call.
 
-Methods are eliminated from the collected data by calling `eliminate_methods!` on the
-profiling result, before submitting it to a printer.
+Methods are eliminated from the collected data by calling
+<tt>eliminate_methods!</tt> on the profiling result, before submitting
+it to a printer.
 
-  result = RubyProf.stop
-  result.eliminate_methods!([/Integer#times/])
+    result = RubyProf.stop
+    result.eliminate_methods!([/Integer#times/])
 
-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).
+The argument given to <tt>eliminate_methods!</tt> is either an array
+of regular expressions, or the name of a file containing a list of
+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.
@@ -135,30 +139,11 @@ 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
+    RubyProf::exclude_threads = [ thread2 ]
+    RubyProf.start
 
 Note that the excluded threads must be specified *before* profiling.
 
-
-== Benchmarking full load time including rubygems startup cost
-
-If you want to get a more accurate measurement of what takes all of a gem's bin/xxx
-command to load, you may want to also measure rubygems' startup penalty.
-You can do this by calling into bin/ruby-prof directly, ex:
-
-  $ gem which ruby-prof
-  g:/192/lib/ruby/gems/1.9.1/gems/ruby-prof-0.10.2/lib/ruby-prof.rb
-
-now run it thus (substitute lib/ruby-prof.rb with bin/ruby-prof):
-
-  $ ruby g:/192/lib/ruby/gems/1.9.1/gems/ruby-prof-0.10.2/bin/ruby-prof g:\192\bin\some_installed_gem_command
-
-or
-
-  $ 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
-
-
 == Profiling Rails
 
 To profile a Rails application it is vital to run it using production like
@@ -170,30 +155,32 @@ profile.rb.
 
 So to profile Rails:
 
-1.  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.
+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
+   files. You should likely turn off caching.
 
-2.  Add the ruby-prof to your gemfile:
+2. Add the ruby-prof to your gemfile:
 
-      group :profile do
-        gem 'ruby-prof'
-      end
+    group :profile do
+      gem 'ruby-prof'
+    end
 
-3.  Add the ruby prof rack adapter to your middleware stack.  One way to
-    do this is by adding the following code to config.ru:
+3. Add the ruby prof rack adapter to your middleware stack.  One way to
+   do this is by adding the following code to <tt>config.ru</tt>:
 
-      if Rails.env.profile?
-        use Rack::RubyProf, :path => '/temp/profile'
-      end
+    if Rails.env.profile?
+      use Rack::RubyProf, :path => '/temp/profile'
+    end
 
-    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.
+   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.
 
-4.  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!
+4. 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!
 
 == Reports
 
@@ -211,7 +198,7 @@ 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].
 
-There are several varieties of these -- run $ ruby-prof --help
+There are several varieties of these - run <tt>ruby-prof --help</tt>
 
 Graph profiles also show the overall time spent in each method. In
 addition, they also show which methods call the current method and which
@@ -236,7 +223,7 @@ 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
 {examples/stack.html}[http://github.com/ruby-prof/ruby-prof/tree/master/examples/stack.html].
 
-Another good example: [http://twitpic.com/28z94a]
+Another good example: http://twitpic.com/28z94a
 
 Finally, there's a so called MultiPrinter which can generate several
 reports in one profiling run. See
@@ -248,106 +235,121 @@ There is also a graphviz .dot visualiser.
 
 Reports are created by printers.  Supported printers include:
 
-* RubyProf::FlatPrinter - Creates a flat report in text format
-* RubyProf::FlatPrinterWithLineNumbers - same as above but more verbose
-* RubyProf::GraphPrinter - Creates a call graph report in text format
-* RubyProf::GraphHtmlPrinter - Creates a call graph report in HTML (separate files per thread)
-* RubyProf::DotPrinter - Creates a call graph report in GraphViz's DOT format which can be converted to an image
-* RubyProf::CallTreePrinter - Creates a call tree report compatible with KCachegrind.
-* RubyProf::CallStackPrinter - Creates a HTML visualization of the Ruby stack
-* RubyProf::MultiPrinter - Uses the other printers to create several reports in one profiling run
-* More!
-
-To use a printer:
-
-  ...
-  result = RubyProf.stop
-  printer = RubyProf::GraphPrinter.new(result)
-  printer.print(STDOUT, :min_percent => 2)
+RubyProf::FlatPrinter::
+  Creates a flat report in text format
 
-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.
+RubyProf::FlatPrinterWithLineNumbers::
+  Same as above but more verbose
 
-The other option is :print_file => true (default false), which adds the filename to the
-output (GraphPrinter only).
+RubyProf::GraphPrinter::
+  Creates a call graph report in text format
 
-The MultiPrinter differs from the other printers in that it requires a directory path
-and a basename for the files it produces.
+RubyProf::GraphHtmlPrinter::
+  Creates a call graph report in HTML (separate files per thread)
 
-   printer = RubyProf::MultiPrinter.new(result)
-   printer.print(:path => ".", :profile => "profile")
+RubyProf::DotPrinter::
+  Creates a call graph report in GraphViz's DOT format which can be converted to an image
 
+RubyProf::CallTreePrinter::
+  Creates a call tree report compatible with KCachegrind
 
-== Measurements
+RubyProf::CallStackPrinter::
+  Creates a HTML visualization of the Ruby stack
 
-Depending on the mode and platform, ruby-prof can measure various
-aspects of a Ruby program.  Supported measurements include:
+RubyProf::MultiPrinter::
+  Uses the other printers to create several reports in one profiling run
 
-* wall time (RubyProf::WALL_TIME)
-* process time (RubyProf::PROCESS_TIME)
-* cpu time (RubyProf::CPU_TIME)
-* object allocations (RubyProf::ALLOCATIONS)
-* memory usage (RubyProf::MEMORY)
-* garbage collection time (RubyProf::GC_TIME)
-* garbage collections runs (RubyProf::GC_RUNS)
+To use a printer:
 
-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.
+    result = RubyProf.stop
+    printer = RubyProf::GraphPrinter.new(result)
+    printer.print(STDOUT, :min_percent => 2)
 
-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.
 
-CPU time uses the CPU clock counter to measure time.  The returned
-values are dependent on the correctly setting the CPU's frequency.
-This mode is only supported on Pentium or PowerPC platforms (linux only).
+The first parameter is any writable IO object such as <tt>STDOUT</tt>
+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.
 
-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.
+The other option is <tt>:print_file => true</tt> (default false),
+which adds the filename to the output (GraphPrinter only).
 
-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.
+<tt>MultiPrinter</tt> differs from the other printers in that it
+requires a directory path and a basename for the files it produces.
 
-Garbage collection time reports how much time is spent in Ruby's
-garbage collector during a profiling session. This support was added
-by Jeremy Kemper and requires a patched Ruby interpreter. See below.
+    printer = RubyProf::MultiPrinter.new(result)
+    printer.print(:path => ".", :profile => "profile")
 
-Garbage collection runs report how many times Ruby's garbage collector
-is invoked during a profiling session. This support was added by
-Jeremy Kemper and requires a patched Ruby interpreter. See below.
+== Measurements
 
-Ruby patches: all of the patches to Ruby are included in the
-railsexpress patchsets for rvm, see https://github.com/skaes/rvm-patchsets
+Depending on the mode and platform, ruby-prof can measure various
+aspects of a Ruby program. Supported measurements include:
+
+RubyProf::WALL_TIME::
+  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.
+
+RubyProf::PROCESS_TIME::
+  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.
+
+RubyProf::CPU_TIME::
+  CPU time uses the CPU clock counter to measure time.  The returned
+  values are dependent on the correctly setting the CPU's frequency.
+  This mode is only supported on Pentium or PowerPC platforms (linux only).
+
+RubyProf::ALLOCATIONS::
+  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.
+
+
+RubyProf::MEMORY::
+  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.
+
+RubyProf::GC_TIME::
+  Garbage collection time reports how much time is spent in Ruby's
+  garbage collector during a profiling session. This support was added
+  by Jeremy Kemper and requires a patched Ruby interpreter. See below.
+
+RubyProf::GC_RUNS::
+ Garbage collection runs report how many times Ruby's garbage collector
+ is invoked during a profiling session. This support was added by
+ Jeremy Kemper and requires a patched Ruby interpreter. See below.
+
+All of the patches to Ruby are included in the railsexpress patchsets
+for rvm, see https://github.com/skaes/rvm-patchsets
 
 To set the measurement:
 
-* RubyProf.measure_mode = RubyProf::WALL_TIME
-* RubyProf.measure_mode = RubyProf::PROCESS_TIME
-* RubyProf.measure_mode = RubyProf::CPU_TIME
-* RubyProf.measure_mode = RubyProf::ALLOCATIONS
-* RubyProf.measure_mode = RubyProf::MEMORY
-* RubyProf.measure_mode = RubyProf::GC_TIME
-* RubyProf.measure_mode = RubyProf::GC_RUNS
+    RubyProf.measure_mode = RubyProf::WALL_TIME
+    RubyProf.measure_mode = RubyProf::PROCESS_TIME
+    RubyProf.measure_mode = RubyProf::CPU_TIME
+    RubyProf.measure_mode = RubyProf::ALLOCATIONS
+    RubyProf.measure_mode = RubyProf::MEMORY
+    RubyProf.measure_mode = RubyProf::GC_TIME
+    RubyProf.measure_mode = RubyProf::GC_RUNS
 
-The default value is RubyProf::WALL_TIME.
+The default value is <tt>RubyProf::WALL_TIME</tt>.
 
-You may also specify the measure_mode by using the RUBY_PROF_MEASURE_MODE
-environment variable:
+You may also specify the measure mode by using the
+<tt>RUBY_PROF_MEASURE_MODE</tt> environment variable:
 
-* export RUBY_PROF_MEASURE_MODE=wall
-* export RUBY_PROF_MEASURE_MODE=process
-* export RUBY_PROF_MEASURE_MODE=cpu
-* export RUBY_PROF_MEASURE_MODE=allocations
-* export RUBY_PROF_MEASURE_MODE=memory
-* export RUBY_PROF_MEASURE_MODE=gc_time
-* export RUBY_PROF_MEASURE_MODE=gc_runs
+    export RUBY_PROF_MEASURE_MODE=wall
+    export RUBY_PROF_MEASURE_MODE=process
+    export RUBY_PROF_MEASURE_MODE=cpu
+    export RUBY_PROF_MEASURE_MODE=allocations
+    export RUBY_PROF_MEASURE_MODE=memory
+    export RUBY_PROF_MEASURE_MODE=gc_time
+    export RUBY_PROF_MEASURE_MODE=gc_runs
 
 On Linux, process time is measured using the clock method provided
 by the C runtime library. Note that the clock method does not
@@ -356,10 +358,10 @@ 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.
 
-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.
+If you set the clock mode to <tt>PROCESS_TIME</tt>, 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.
 
 If you use wall time, the results will be affected by other
 processes running on your computer, network delays, disk access,
@@ -369,7 +371,7 @@ otherwise quiescent.
 
 == Multi-threaded Applications
 
-Unfortunately, Ruby does not provide an internal api
+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
@@ -397,4 +399,4 @@ See LICENSE for license information.
 
 Code is located at https://github.com/ruby-prof/ruby-prof
 
-Google group/mailing list: http://groups.google.com/group/ruby-optimization or start a github issue.
+Google group/mailing list: http://groups.google.com/group/ruby-optimization or open a github issue.