@@ -1,4 +1,46 @@ -0.6.0 (2007-02-03) +0.6.1 (2008-02-25) +======================== + +ruby-prof 0.6.1 add support for profiling tests cases. + +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. + + +Fixes +------- +* RubyProf.profile no longer crashes if an exception is + thrown during a profiling run. + + +0.6.0 (2008-02-03) ======================== ruby-prof 0.6.0 adds support for Ruby 1.9 and memory profiling. CHANGES @@ -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: @@ -271,6 +378,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 +402,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 README @@ -7,7 +7,7 @@ require 'date' SO_NAME = "ruby_prof.so" # ------- Default Package ---------- -RUBY_PROF_VERSION = "0.6.0" +RUBY_PROF_VERSION = "0.6.1" FILES = FileList[ 'Rakefile', Rakefile mingw/ruby_prof.so 4f70a3c4c54cab50b5aacde46882e558e79313dc cfis cfis@5fb4a865-4516-0410-ae3b-a609ddf12040 http://github.com/jeremy/ruby-prof/commit/51a4414bffc2731a5cbe232551fc053bf57b3021 51a4414bffc2731a5cbe232551fc053bf57b3021

2008-02-24T22:38:17-08:00

Documentation updates for 0.6.1 and profiling rails. git-svn-id: http://ruby-prof.rubyforge.org/svn@251 5fb4a865-4516-0410-ae3b-a609ddf12040 d6d5eac7a24ffbe0e303979228236f4e84ae7b11 cfis cfis@5fb4a865-4516-0410-ae3b-a609ddf12040