ruby-prof 0.16.2 → 1.1.0

data/LICENSE

@@ -1,25 +1,25 @@
-Copyright (C) 2005 - 2014 Shugo Maeda <shugo@ruby-lang.org> and Charlie Savage <cfis@savagexi.com>
-Copyright (C) 2010 - 2014 Stefan Kaes <skaes@railsepxress.de>
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions
-are met:
-
-1. Redistributions of source code must retain the above copyright
-   notice, this list of conditions and the following disclaimer.
-2. 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.
-
-THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' 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
+Copyright (C) 2005 - 2019 Shugo Maeda <shugo@ruby-lang.org>, Charlie Savage <cfis@savagexi.com> and
+                          Stefan Kaes <skaes@railsepxress.de>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. 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.
+
+THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' 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.

data/README.rdoc

@@ -1,454 +1,5 @@
-= 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 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.
-* Reports - can generate text and cross-referenced html reports
-  - 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.
-* Threads - supports profiling multiple threads simultaneously
-
-== Requirements
-
-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 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.
-
-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:
-
-    gem install ruby-prof
-
-If you're on windows then please install the devkit first so that it
-can compile.
-
-== Usage
-
-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
-
-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.
-
-
-=== ruby-prof Convenience API
-
-The second way is to use the ruby-prof convenience API to profile
-particular segments of code.
-
-    require 'ruby-prof'
-
-    # 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)
-
-Alternatively, you can use a block to tell ruby-prof what to profile:
-
-    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, {})
-
-ruby-prof also supports pausing and resuming profiling runs.
-
-    require 'ruby-prof'
-
-    # profile the code
-    RubyProf.start
-    # ... code to profile ...
-
-    RubyProf.pause
-    # ... other code ...
-
-    RubyProf.resume
-    # ... code to profile ...
-    result = RubyProf.stop
-
-Note that resume will only work if start has been called previously.
-In addition, resume can also take a block:
-
-    require 'ruby-prof'
-
-    RubyProf.resume do
-      # ... code to profile...
-    end
-
-    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
-
-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
-call graph, making it easier to identify the source of performance
-problems when using a graph printer.
-
-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
-<tt>eliminate_methods!</tt> on the profiling result, before submitting
-it to a printer.
-
-    result = RubyProf.stop
-    result.eliminate_methods!([/Integer#times/])
-
-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.
-
-
-== Profiling Rails
-
-To profile a Rails application it is vital to run it using production like
-settings (cache classes, cache view lookups, etc.).  Otherwise, Rail'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.
-
-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 overwhelmed by the time Rails spends loading required
-   files. You should likely turn off caching.
-
-2. Add the ruby-prof to your gemfile:
-
-    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 <tt>config.ru</tt>:
-
-    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.
-
-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
-
-ruby-prof can generate a number of different reports:
-
-* Flat Reports
-* Graph Reports
-* HTML Graph Reports
-* Call graphs
-* Call stack reports
-* More!
-
-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
-{examples/flat.txt}[http://github.com/ruby-prof/ruby-prof/tree/master/examples/flat.txt].
-
-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
-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
-{examples/graph.txt}[http://github.com/ruby-prof/ruby-prof/tree/master/examples/graph.txt].
-
-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
-{examples/graph.html}[http://github.com/ruby-prof/ruby-prof/tree/master/examples/graph.html].
-
-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
-{KCachegrind}[http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindCalltreeFormat]
-site.
-
-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
-
-Finally, there's a so called MultiPrinter which can generate several
-reports in one profiling run. See
-{examples/multi.stack.html}[http://github.com/ruby-prof/ruby-prof/tree/master/examples/multi.stack.html].
-
-There is also a graphviz .dot visualiser.
-
-== Printers
-
-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
-
-To use a printer:
-
-    result = RubyProf.stop
-    printer = RubyProf::GraphPrinter.new(result)
-    printer.print(STDOUT, :min_percent => 2)
-
-
-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.
-
-The other option is <tt>:print_file => true</tt> (default false),
-which adds the filename to the output (GraphPrinter only).
-
-<tt>MultiPrinter</tt> differs from the other printers in that it
-requires a directory path and a basename for the files it produces.
-
-    printer = RubyProf::MultiPrinter.new(result)
-    printer.print(:path => ".", :profile => "profile")
-
-== Measurements
-
-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.
-
-== Patching ruby
-
-All of the patches to Ruby are included in the railsexpress 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:
-
-    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 <tt>RubyProf::WALL_TIME</tt>.
-
-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
-
-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.
-
-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,
-etc.  As result, for the best results, try to make sure your
-computer is only performing your profiling run and is
-otherwise quiescent.
-
-== Multi-threaded Applications
-
-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
-
-Significant effort has been put into reducing ruby-prof'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.
-
-== License
-
-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
-
-Google group/mailing list: http://groups.google.com/group/ruby-optimization or open a github issue.
+= 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]
+
+For an overview of ruby-prof please see https://ruby-prof.github.io