ruby-prof 0.6.0 → 0.7.0

data/CHANGES

@@ -1,4 +1,57 @@
-0.6.0 (2007-02-03)
+0.7.0 (2008-11-04)
+========================
+
+Features
+--------
+* Added two new methods - RubyProf.resume and RubyProf.pause. 
+  RubyProf.resume takes an optional block, which ensures that
+  RubyProf.pause is called.  For example:
+  
+  10.times do |i|
+    RubyProf.resume do
+      # Some long process
+    end
+  end
+  
+  result = RubyProf.stop
+
+* Added support for profiling tests that use Ruby's built-in
+  unit test framework (ie, test derived from 
+  Test::Unit::TestCase).  To enable profiling simply add
+  the following line of code to your test class:
+  
+    include RubyProf::Test
+    
+  By default, profiling results are written to the current 
+  processes working directory.  To change this, or other
+  profiling options, simply modify the PROFILE_OPTIONS hash
+  table as needed.        
+
+* Used the new support for profiling test cases to revamp
+  the way that Rails profiling works.  For more information
+  please refer to RubyProf's documentation.
+
+* Keep track of call stack for each method to enable more
+  powerful profile visualizations in Integrated Development
+  Environments (Hin Boean, work supported by CodeGear).
+
+* Expose measurements to Ruby (Jeremy Kemper).
+
+* Add support for additional memory measurements modes in Ruby 1.9 (Jeremy Kemper).
+
+* Add support for Lloyd Hilaiel's Ruby patch for measuring total heap size.
+   See http://lloydforge.org/projects/ruby. (Jeremy Kemper).
+  
+  
+Fixes
+-------
+* RubyProf.profile no longer crashes if an exception is
+  thrown during a profiling run.
+
+* Measure memory in fractional kilobytes rather than rounding down (Jeremy Kemper)
+
+  
+0.6.0 (2008-02-03)
 ========================
 
 ruby-prof 0.6.0 adds support for Ruby 1.9 and memory profiling.

data/README

@@ -41,12 +41,14 @@ ruby-prof is also available as a tarred gzip archive and zip archive.
 
 There are three ways of running ruby-prof.
 
+
 === 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 ruby-prof documentation[link:files/bin/ruby-prof.html].
 
+
 === ruby-prof API
 
 The second way is to use the ruby-prof API to profile
@@ -81,7 +83,36 @@ to profile:
   printer = RubyProf::GraphPrinter.new(result)
   printer.print(STDOUT, 0)
 
+Starting with the 0.6.1 release, 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 automatically call start if a profiling run
+has not yet started.  In addition, resume can also take a block:
+
+  require 'ruby-prof'
+  
+  # Profile the code
+  RubyProf.resume do
+    [code to profile]
+  end
+
+  data = RubyProf.stop
   
+With this usage, resume will automatically call pause at the 
+end of the block.
+
+
 === require unprof
 
 The third way of using ruby-prof is by requiring unprof.rb:
@@ -93,7 +124,82 @@ using a flat profile report.
 
 This method is provided for backwards compatibility.  Using
 {ruby-prof}[link:files/bin/ruby-prof.html] provides more flexibility.
+
+
+== Profiling Tests
+
+Starting with the 0.6.1 release, ruby-prof supports profiling tests cases
+written using Ruby's built-in	unit test framework (ie, test derived from 
+Test::Unit::TestCase).  To enable profiling simply add the following line 
+of code to your test class:
   
+  	include RubyProf::Test
+  	
+Each test method is profiled separately.  ruby-prof will run each test method
+once as a warmup and then ten additional times to gather profile data.
+Note that the profile data will *not* include the class's setup or 
+teardown methods.
+
+Separate reports are generated for each method and saved, by default, 
+in the test process's working directory.  To change this, or other profiling
+options, modify your test class's PROFILE_OPTIONS hash table. To globally 
+change test profiling options, modify RubyProf::Test::PROFILE_OPTIONS.  
+
+
+== 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 - or simply copy the example file
+    in ruby-prof/rails/environment/profile.rb
+    
+2.  Copy the file:
+     
+      ruby-prof/rails/profile_test_helper.rb 
+    
+    To:
+    
+      your_rails_app/test/profile_test_helper.rb
+
+3.  Create a new test directory for profiling:
+
+      your_rails_app/test/profile
+    
+
+4.  Write unit, functional or integration tests specifically designed
+    to profile some part of your Rails application.  At the top
+    of each test, replace this line:
+    
+      require File.dirname(__FILE__) + '/../test_helper'
+
+    With:
+    
+      require File.dirname(__FILE__) + '/../profile_test_helper'
+
+    For example:
+
+    require File.dirname(__FILE__) + '/../profile_test_helper'
+    
+    class ExampleTest < Test::Unit::TestCase
+      include RubyProf::Test
+      fixtures ....
+      
+      def test_stuff
+        puts "Test method"
+      end
+    end   
+
+5.  Now run your tests.  Results will be written to:
+
+      your_rails_app/tmp/profile
+    
 
 == Reports
 
@@ -133,6 +239,7 @@ by KCachegrind.  Call graph support was generously donated by Carl Shimer.
 More information about the format can be found at
 the {KCachegrind}[link:http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindCalltreeFormat] site.
 
+
 == Printers
 
 Reports are created by printers.  Supported printers include:
@@ -160,11 +267,14 @@ information please see the documentation for the different printers.
 Depending on the mode and platform, ruby-prof can measure various
 aspects of a Ruby program.  Supported measurements include:
 
-* process time
-* wall time
-* cpu time
-* object allocations
-* memory usage
+* process time (RubyProf::PROCESS_TIME)
+* wall time (RubyProf::WALL_TIME)
+* cpu time (RubyProf::CPU_TIME)
+* object allocations (RubyProf::ALLOCATIONS)
+* memory usage (RubyProf::MEMORY)
+* garbage collections runs (RubyProf::GC_RUNS)
+* garbage collection time (RubyProf::GC_TIME)
+
 
 Process time measures the time used by a process between any two moments.
 It is unaffected by other processes concurrently running 
@@ -182,14 +292,24 @@ This mode is only supported on Pentium or PowerPC platforms.
 
 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.  For more information, see:
+and requires a patched Ruby interpreter.  For more information and
+the patch, please see:
 http://rubyforge.org/tracker/index.php?func=detail&aid=11497&group_id=426&atid=1700
 
 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.  For more information, see:
-http://rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062.
+http://rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062
 
+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.  For more information, see:
+http://rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062
+
+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.  For more information, see:
+http://rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062
 
 To set the measurement:
 
@@ -198,6 +318,8 @@ To set the measurement:
 * RubyProf.measure_mode = RubyProf::CPU_TIME
 * RubyProf.measure_mode = RubyProf::ALLOCATIONS
 * RubyProf.measure_mode = RubyProf::MEMORY
+* RubyProf.measure_mode = RubyProf::GC_RUNS
+* RubyProf.measure_mode = RubyProf::GC_TIME
 
 The default value is RubyProf::PROCESS_TIME.
 
@@ -208,6 +330,9 @@ environment variable:
 * export RUBY_PROF_MEASURE_MODE=wall
 * export RUBY_PROF_MEASURE_MODE=cpu
 * export RUBY_PROF_MEASURE_MODE=allocations
+* export RUBY_PROF_MEASURE_MODE=memory
+* export RUBY_PROF_MEASURE_MODE=gc_runs
+* export RUBY_PROF_MEASURE_MODE=gc_time
   
 Note that these values have changed since ruby-prof-0.3.0.  
 
@@ -271,6 +396,7 @@ 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.
 
+
 == Multi-threaded Applications
 
 Unfortunately, Ruby does not provide an internal api
@@ -294,6 +420,7 @@ profiled.  Most programs will run approximately twice as slow
 while highly recursive programs (like the fibonacci series test)
 will run three times slower.
 
+
 == Windows Binary
 
 The Windows binary is built with the latest version of MinGW.  The source

data/Rakefile

@@ -1,25 +1,33 @@
 require 'rubygems'
-require 'date'
 require 'rake/gempackagetask'
 require 'rake/rdoctask'
+require 'rake/testtask'
 require 'date'
 
-SO_NAME = "ruby_prof.so"
+# ------- Version ----
+# Read version from header file
+version_header = File.read('ext/version.h')
+match = version_header.match(/RUBY_PROF_VERSION\s*["](\d.+)["]/)
+raise(RuntimeError, "Could not determine RUBY_PROF_VERSION") if not match
+RUBY_PROF_VERSION = match[1]
+  
 
 # ------- Default Package ----------
-RUBY_PROF_VERSION = "0.6.0"
-
 FILES = FileList[
   'Rakefile',
   'README',
   'LICENSE',
   'CHANGES',
   'bin/*',
-  'lib/**/*',
-  'rails_plugin/**/*',
+  'doc/**/*',
   'examples/*',
   'ext/*',
-  'doc/**/*',
+  'ext/mingw/Rakefile',
+  'ext/mingw/build.rake',
+  'ext/vc/*.sln',
+  'ext/vc/*.vcproj',
+  'lib/**/*',
+  'rails/**/*',
   'test/*'
 ]
 
@@ -57,56 +65,31 @@ EOF
   
   # rdoc
   spec.has_rdoc = true
-  spec.rdoc_options << "--title" << "ruby-prof"
-  # Show source inline with line numbers
-  spec.rdoc_options << "--inline-source" << "--line-numbers"
-  # Make the readme file the start page for the generated html
-  spec.rdoc_options << '--main' << 'README'
-  spec.extra_rdoc_files = ['bin/ruby-prof',
-                           'ext/ruby_prof.c',
-                           'examples/flat.txt',
-                           'examples/graph.txt',
-                           'examples/graph.html',
-                           'README',
-                           'LICENSE']
-
 end
 
 # Rake task to build the default package
 Rake::GemPackageTask.new(default_spec) do |pkg|
   pkg.need_tar = true
-  pkg.need_zip = true
+  #pkg.need_zip = true
 end
 
 
 # ------- Windows Package ----------
-# Windows specification
-win_spec = default_spec.clone
-win_spec.extensions = []
-win_spec.platform = Gem::Platform::CURRENT
-win_spec.files += ["lib/#{SO_NAME}"]
-
-desc "Create Windows Gem"
-task :create_win32_gem do
-  # Copy the win32 extension built by MingW - easier to install
-  # since there are no dependencies of msvcr80.dll
-  current_dir = File.expand_path(File.dirname(__FILE__))
-  source = File.join(current_dir, "mingw", SO_NAME)
-  target = File.join(current_dir, "lib", SO_NAME)
-  cp(source, target)
-
-  # Create the gem, then move it to pkg
-  Gem::Builder.new(win_spec).build
-  gem_file = "#{win_spec.name}-#{win_spec.version}-#{win_spec.platform}.gem"
-  mv(gem_file, "pkg/#{gem_file}")
-
-  # Remove win extension from top level directory  
-  rm(target)
+if RUBY_PLATFORM.match(/win32/)
+  binaries = (FileList['ext/mingw/*.so',
+                       'ext/mingw/*.dll*'])
+
+  # Windows specification
+  win_spec = default_spec.clone
+  win_spec.extensions = ['ext/mingw/Rakefile']
+  win_spec.platform = Gem::Platform::CURRENT
+  win_spec.files += binaries.to_a
+
+  # Rake task to build the windows package
+  Rake::GemPackageTask.new(win_spec) do |pkg|
+  end
 end
 
-
-task :package => :create_win32_gem
-
 # ---------  RDoc Documentation ------
 desc "Generate rdoc documentation"
 Rake::RDocTask.new("rdoc") do |rdoc|
@@ -122,20 +105,19 @@ Rake::RDocTask.new("rdoc") do |rdoc|
                           'examples/graph.txt',
                           'examples/graph.html',
                           'lib/**/*.rb',
-                          'ext/**/ruby_prof.c',
+                          'ext/ruby_prof.c',
+                          'ext/version.h',
+                          'ext/measure_*.h',
                           'README',
                           'LICENSE')
 end
 
+task :default => :package
 
-# ---------  Publish to RubyForge  ----------------
-desc "Publish ruby-prof to RubyForge."
-task :publish do 
-  require 'rake/contrib/sshpublisher'
-  
-  # Get ruby-prof path
-  ruby_prof_path = File.expand_path(File.dirname(__FILE__))
-
-  publisher = Rake::SshDirPublisher.new("cfis@rubyforge.org",
-        "/var/www/gforge-projects/ruby-prof", ruby_prof_path)
-end
+desc 'Run the ruby-prof test suite'
+Rake::TestTask.new do |t|
+  t.libs += %w(lib ext test)
+  t.test_files = Dir['test/*_test.rb'] - %w(test/profile_unit_test.rb)
+  t.verbose = true
+  t.warning = true
+end

data/bin/ruby-prof

@@ -6,7 +6,7 @@
 #
 # == Usage
 #
-# ruby_prof [options] <script.rb> [options-for-script]
+# ruby_prof [options] <script.rb> [--] [script-options]"
 #
 # Options:
 #     -p, --printer=printer            Select a printer:
@@ -25,6 +25,12 @@
 #                                              (only supported on Pentium and PowerPCs).
 #                                        allocations - Tracks object allocations
 #                                              (requires a patched Ruby interpreter).
+#                                        memory - Tracks total memory size
+#                                              (requires a patched Ruby interpreter).
+#                                        gc_runs - Tracks number of garbage collection runs
+#                                              (requires a patched Ruby interpreter).
+#                                        gc_time - Tracks time spent doing garbage collection
+#                                              (requires a patched Ruby interpreter).
 #         --replace-progname           Replace $0 when loading the .rb files.
 #         --specialized-instruction    Turn on specialized instruction.
 #     -h, --help                       Show help message
@@ -48,7 +54,7 @@ options.specialized_instruction = false
 
 opts = OptionParser.new do |opts|
   opts.banner = "ruby_prof #{RubyProf::VERSION}\n" +
-                "Usage: ruby_prof [options] <script.rb> [--extra-options-for-script]"
+                "Usage: ruby_prof [options] <script.rb> [--] [script-options]"
  
   opts.separator ""
   opts.separator "Options:"
@@ -87,12 +93,15 @@ opts = OptionParser.new do |opts|
   end
     
   opts.on('--mode=measure_mode',
-      [:process, :wall, :cpu, :allocations],
+      [:process, :wall, :cpu, :allocations, :memory, :gc_runs, :gc_time],
       'Select what ruby-prof should measure:',
       '  process - Process time (default).',
       '  wall - Wall time.',
       '  cpu - CPU time (Pentium and PowerPCs only).',
-      '  allocations - Object allocations (requires patched Ruby interpreter).') do |measure_mode|
+      '  allocations - Object allocations (requires patched Ruby interpreter).',
+      '  memory - Allocated memory in KB (requires patched Ruby interpreter).',
+      '  gc_runs - Number of garbage collections (requires patched Ruby interpreter).',
+      '  gc_time - Time spent in garbage collection (requires patched Ruby interpreter).') do |measure_mode|
       
       case measure_mode
       when :process
@@ -103,6 +112,12 @@ opts = OptionParser.new do |opts|
         options.measure_mode = RubyProf::CPU_TIME
       when :allocations
         options.measure_mode = RubyProf::ALLOCATIONS
+      when :memory
+        options.measure_mode = RubyProf::MEMORY
+      when :gc_runs
+        options.measure_mode = RubyProf::GC_RUNS
+      when :gc_time
+        options.measure_mode = RubyProf::GC_TIME
       end
   end
         
@@ -182,11 +197,11 @@ end
 # Get the script we will execute
 script = ARGV.shift
 if options.replace_prog_name
-        $0 = File.basename(File.expand_path(script))
+  $0 = File.expand_path(script)
 end
 
 # Start profiling
 RubyProf.start 
 
 # Load the script
-load script
+load script