ruby-prof 0.4.0 → 0.4.1

data/README

@@ -1,220 +1,220 @@
-= ruby-prof
-
-== Overview
-
-ruby-prof is a fast code profiler for Ruby.  Its features include:
-
-* Speed - it is a C extension and therefore many times faster than the standard Ruby profiler.
-* 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.
-* Threads - supports profiling multiple threads simultaneously
-* Recursive calls - supports profiling recursive method calls
-* Reports - can generate both text and cross-referenced html reports
-* Output - can output to standard out or to a file
-
-
-== Requirements
-
-ruby-prof requires Ruby 1.8.2 or higher.
-
-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 install the Windows specific RubyGem which
-includes an already built extension.
-
-
-== Install
-
-ruby-prof is provided as a RubyGem.  To install:
-
-<tt>gem install ruby-prof</tt>
-
-If you are running Windows, make sure to install the Win32 RubyGem which 
-includes a pre-built binary.
-
-== Usage
-
-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
-particular segments of code.  
-
-  require 'ruby-prof'
-  
-  # Profile the code
-  RubyProf.start
-  ...
-  [code to profile]
-  ...
-  result = RubyProf.end
-  
-  # Print a flat profile to text
-  printer = RubyProf::TextPrinter.new(result)
-  printer.print(STDOUT, 0)
-	
-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, 0)
-
-  
-=== require unprof
-
-The third way of using ruby-prof is by requiring unprof.rb:
-
-	require 'unprof'
-
-This will start profiling immediately and will output the results
-using a flat profile report.
-
-This method is provided for backwards compatibility.  Using
-{ruby-prof}[link:files/bin/ruby-prof.html] provides more flexibility.
-  
-
-== Reports
-
-ruby-prof can generate flat profile and graph profile reports.
-
-Flat profiles show the overall time spent in each method.  They
-are a good 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}[link:files/examples/flat_txt.html].
-
-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.  Graph profiles can be generated
-in text and html.  Since the html is cross-referenced it is
-easier to work with.  An example text graph profile
-is located at {examples/graph.txt}[link:files/examples/graph_txt.html] while
-an example html graph file is located at 
-{examples/graph.html}[link:files/examples/graph_html.html].
-
-Reports are created by printers.  The current printers include:
-* RubyProf::FlatPrinter - Creates a flat report in text format
-* RubyProf::GraphPrinter - Creates a call graph report in text format
-* RubyProf::GraphHtmlPrinter - Creates a call graph report in HTML (separate files per thread)
-
-To use a printer:
-
-  result = RubyProf.end
-  printer = RubyProf::GraphPrinter.new(result)
-  printer.print(STDOUT, 0)
-
-The first parameter is any writable IO object such as STDOUT or a file.
-The second parameter, which has a default value of 0, specifies 
-the minimum percentage a method must take to be printed.  For more
-information please see the documentation for the different printers.
-
-
-== Timing Data
-
-Depending on the mode and platform, ruby-prof can measure time in 
-three ways - process time, wall time and cpu 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 - therefore, all measurements on Windows use 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 too large.
-
-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.
-
-To set the clock_mode:
-
-	RubyProf.clock_mode = RubyProf::PROCESS_TIME
-	RubyProf.clock_mode = RubyProf::WALL_TIME
-	RubyProf.clock_mode = RubyProf::CPU_TIME
-
-This default value is PROCESS_TIME.
-
-You may also specify the clock_mode by using the RUBY_PROF_CLOCK_MODE
-environment variable:
-
-	export RUBY_PROF_CLOCK_MODE=process
-	export RUBY_PROF_CLOCK_MODE=wall
-	export RUBY_PROF_CLOCK_MODE=cpu
-	
-Note that these values have changed since ruby-prof-0.3.0.	
-
-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.
-
-On Windows, timings are always wall times.  If you set the clock 
-mode to PROCESS_TIME, then timing 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.
-
-On both platforms, cpu time is measured using the RDTSC assembly
-function provided by the Pentium and PowerPC platforms. CPU time
-is dependent on the cpu's frequency.  On Linux, ruby-prof attempts 
-to read this value from "/proc/cpuinfo."  On Windows, you must
-specify the clock frequency.  This can be done using the
-RUBY_PROF_CPU_FREQUENCY environment variable:
-
-	export RUBY_PROF_CPU_FREQUENCY=<value>
-	
-You can also directly set the cpu frequency by calling:
-
-	RubyProf.cpu_frequency = <value> 
-
-
-== Recursive Calls
-
-Recursive calls occur when method A calls method A and cycles
-occur when method A calls method B calls method C calls method A.
-ruby-prof can detect recursive calls any cycle calls, but does not
-currently report these in its output.
-
-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.
-
-== 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.  On the low end overhead is around 10% while on the
-high end its can around 80%.
-
-== Windows Binary
-
-The Windows binary is built with the latest version of MinGW.
-
-
-== License
-
-See LICENSE for license information.
+= ruby-prof
+
+== Overview
+
+ruby-prof is a fast code profiler for Ruby.  Its features include:
+
+* Speed - it is a C extension and therefore many times faster than the standard Ruby profiler.
+* 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.
+* Threads - supports profiling multiple threads simultaneously
+* Recursive calls - supports profiling recursive method calls
+* Reports - can generate both text and cross-referenced html reports
+* Output - can output to standard out or to a file
+
+
+== Requirements
+
+ruby-prof requires Ruby 1.8.2 or higher.
+
+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 install the Windows specific RubyGem which
+includes an already built extension.
+
+
+== Install
+
+ruby-prof is provided as a RubyGem.  To install:
+
+<tt>gem install ruby-prof</tt>
+
+If you are running Windows, make sure to install the Win32 RubyGem which 
+includes a pre-built binary.
+
+== Usage
+
+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
+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::TextPrinter.new(result)
+  printer.print(STDOUT, 0)
+	
+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, 0)
+
+  
+=== require unprof
+
+The third way of using ruby-prof is by requiring unprof.rb:
+
+	require 'unprof'
+
+This will start profiling immediately and will output the results
+using a flat profile report.
+
+This method is provided for backwards compatibility.  Using
+{ruby-prof}[link:files/bin/ruby-prof.html] provides more flexibility.
+  
+
+== Reports
+
+ruby-prof can generate flat profile and graph profile reports.
+
+Flat profiles show the overall time spent in each method.  They
+are a good 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}[link:files/examples/flat_txt.html].
+
+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.  Graph profiles can be generated
+in text and html.  Since the html is cross-referenced it is
+easier to work with.  An example text graph profile
+is located at {examples/graph.txt}[link:files/examples/graph_txt.html] while
+an example html graph file is located at 
+{examples/graph.html}[link:files/examples/graph_html.html].
+
+Reports are created by printers.  The current printers include:
+* RubyProf::FlatPrinter - Creates a flat report in text format
+* RubyProf::GraphPrinter - Creates a call graph report in text format
+* RubyProf::GraphHtmlPrinter - Creates a call graph report in HTML (separate files per thread)
+
+To use a printer:
+
+  result = RubyProf.end
+  printer = RubyProf::GraphPrinter.new(result)
+  printer.print(STDOUT, 0)
+
+The first parameter is any writable IO object such as STDOUT or a file.
+The second parameter, which has a default value of 0, specifies 
+the minimum percentage a method must take to be printed.  For more
+information please see the documentation for the different printers.
+
+
+== Timing Data
+
+Depending on the mode and platform, ruby-prof can measure time in 
+three ways - process time, wall time and cpu 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 - therefore, all measurements on Windows use 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 too large.
+
+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.
+
+To set the clock_mode:
+
+	RubyProf.clock_mode = RubyProf::PROCESS_TIME
+	RubyProf.clock_mode = RubyProf::WALL_TIME
+	RubyProf.clock_mode = RubyProf::CPU_TIME
+
+This default value is PROCESS_TIME.
+
+You may also specify the clock_mode by using the RUBY_PROF_CLOCK_MODE
+environment variable:
+
+	export RUBY_PROF_CLOCK_MODE=process
+	export RUBY_PROF_CLOCK_MODE=wall
+	export RUBY_PROF_CLOCK_MODE=cpu
+	
+Note that these values have changed since ruby-prof-0.3.0.	
+
+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.
+
+On Windows, timings are always wall times.  If you set the clock 
+mode to PROCESS_TIME, then timing 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.
+
+On both platforms, cpu time is measured using the RDTSC assembly
+function provided by the Pentium and PowerPC platforms. CPU time
+is dependent on the cpu's frequency.  On Linux, ruby-prof attempts 
+to read this value from "/proc/cpuinfo."  On Windows, you must
+specify the clock frequency.  This can be done using the
+RUBY_PROF_CPU_FREQUENCY environment variable:
+
+	export RUBY_PROF_CPU_FREQUENCY=<value>
+	
+You can also directly set the cpu frequency by calling:
+
+	RubyProf.cpu_frequency = <value> 
+
+
+== Recursive Calls
+
+Recursive calls occur when method A calls method A and cycles
+occur when method A calls method B calls method C calls method A.
+ruby-prof can detect recursive calls any cycle calls, but does not
+currently report these in its output.
+
+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.
+
+== 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.  On the low end overhead is around 10% while on the
+high end its can around 80%.
+
+== Windows Binary
+
+The Windows binary is built with the latest version of MinGW.
+
+
+== License
+
+See LICENSE for license information.

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/rdoctask'
 SO_NAME = "ruby_prof.so"
 
 # ------- Default Package ----------
-RUBY_PROF_VERSION = "0.4.0"
+RUBY_PROF_VERSION = "0.4.1"
 
 FILES = FileList[
   'Rakefile',
@@ -73,8 +73,8 @@ end
 
 # Rake task to build the default package
 Rake::GemPackageTask.new(default_spec) do |pkg|
-	pkg.need_zip = false
-  pkg.need_tar = false
+  pkg.need_tar = true
+  pkg.need_tar = true
 end