ruby-prof 0.4.0-mswin32

data/CHANGES

@@ -0,0 +1,17 @@
+
+0.4.0 (2006-06-16)
+========================
+Features
+--------
+* added support for call graphs
+* added support for printers.  Currently there is a FlatPrinter,
+  GraphPrinter and GraphHtmlPrinter.
+* added support for recursive methods
+* added Windows support
+* now packaged as a RubyGem
+
+Fixes
+-------
+* Fixes bug where RubyProf would crash depending on the
+  way it was invoked - for example, it did not run when
+  used with Arachno Ruby's customized version of Ruby.

data/LICENSE

@@ -0,0 +1,23 @@
+Copyright (C) 2005  Shugo Maeda <shugo@ruby-lang.org>
+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

@@ -0,0 +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.

data/Rakefile

@@ -0,0 +1,141 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+
+SO_NAME = "ruby_prof.so"
+
+# ------- Default Package ----------
+RUBY_PROF_VERSION = "0.4.0"
+
+FILES = FileList[
+  'Rakefile',
+  'README',
+  'LICENSE',
+  'CHANGES',
+  'bin/*',
+  'lib/**/*',
+  'examples/*',
+  'ext/*',
+  'doc/**/*',
+  'test/*'
+]
+
+# Default GEM Specification
+default_spec = Gem::Specification.new do |spec|
+  spec.name = "ruby-prof"
+  
+  spec.homepage = "http://rubyforge.org/projects/ruby-prof/"
+  spec.summary = "Fast Ruby profiler"
+  spec.description = <<-EOF
+ruby-prof is a fast code profiler for Ruby. It is a C extension and
+therefore is many times faster than the standard Ruby profiler. It
+supports both flat and graph profiles.  For each method, graph profiles
+show how long the method ran, which methods called it and which 
+methods it called. RubyProf generate both text and html and can output
+it to standard out or to a file.
+EOF
+
+  spec.version = RUBY_PROF_VERSION
+
+  spec.author = "Shugo Maeda and Charlie Savage"
+  spec.email = "shugo@ruby-lang.org and cfis@savagexi.com"
+  spec.platform = Gem::Platform::RUBY
+  spec.require_path = "lib" 
+  spec.bindir = "bin"
+  spec.executables = ["ruby-prof"]
+  spec.extensions = ["ext/extconf.rb"]
+  spec.autorequire = "ruby-prof"
+  spec.files = FILES.to_a
+  spec.test_files = Dir["test/test_*.rb"]
+  
+
+  spec.required_ruby_version = '>= 1.8.2'
+	spec.date = DateTime.now
+  spec.rubyforge_project = 'ruby-prof'
+  
+  # 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',
+                           'examples/flat.txt',
+  											   'examples/graph.txt',
+  											   'examples/graph.html',
+    											 'ext/ruby_prof.c',
+    											 'README',
+    											 'LICENSE']
+
+end
+
+
+# Rake task to build the default package
+Rake::GemPackageTask.new(default_spec) do |pkg|
+	pkg.need_zip = false
+  pkg.need_tar = false
+end
+
+
+# ------- Windows Package ----------
+
+# Windows specification
+win_spec = default_spec.clone
+win_spec.extensions = []
+win_spec.platform = Gem::Platform::WIN32
+win_spec.files += ["lib/#{SO_NAME}"]
+
+
+desc "Create Windows Gem"
+task :create_win32_gem do
+  # Copy the win32 extension the top level directory
+  current_dir = File.expand_path(File.dirname(__FILE__))
+  source = File.join(current_dir, "ext", "win32", 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 fro top level directory	
+	rm(target)
+end
+
+task :package => :create_win32_gem
+
+# ---------  RDoc Documentation ------
+desc "Generate rdoc documentation"
+Rake::RDocTask.new("rdoc") do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "ruby-prof"
+  # Show source inline with line numbers
+  rdoc.options << "--inline-source" << "--line-numbers"
+  # Make the readme file the start page for the generated html
+  rdoc.options << '--main' << 'README'
+  rdoc.rdoc_files.include('bin/**/*',
+  											  'doc/*.rdoc',
+  											  'examples/flat.txt',
+  											  'examples/graph.txt',
+  											  'examples/graph.html',
+                          'lib/**/*.rb',
+    											'ext/**/ruby_prof.c',
+    											'README',
+    											'LICENSE')
+end
+
+
+
+# ---------  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

data/bin/ruby-prof

@@ -0,0 +1,154 @@
+#! /usr/bin/env ruby
+
+# == Synopsis
+#
+# Profiles a Ruby program.
+#
+# == Usage
+#
+# ruby_prof [options] <script.rb> [options-for-script]
+#
+# Options:
+#     -p, --printer=printer            Select a printer:
+#                                        flat - Prints a flat profile as text (default).
+#                                        graph - Prints a graph profile as text.
+#                                        graph_html - Prints a graph profile as html.
+#     -f, --file=path                  Output results to a file instead of standard out.
+#     -c, --clock-mode=clock_mode      Select a clock mode:
+#                                        process - Use process time (default).
+#                                        wall - Use wall time.
+#                                        cpu - Use the CPU clock counter
+#                                              (only supported on Pentium and PowerPCs).
+#     -h, --help                       Show help message
+#         --version                    Show version
+# 
+#
+# See also: {flat profiles}[link:files/examples/flat_txt.html], {graph profiles}[link:files/examples/graph_txt.html], {html graph profiles}[link:files/examples/graph_html.html]
+#
+
+
+require 'ostruct'
+require 'optparse'
+require 'ruby-prof'
+
+options = OpenStruct.new
+options.clock_mode = RubyProf::PROCESS_TIME
+options.printer = RubyProf::FlatPrinter
+options.min_percent = 0
+options.file = nil
+
+opts = OptionParser.new do |opts|
+	opts.banner = "ruby_prof #{RubyProf::VERSION}\n" +
+	              "Usage: ruby_prof [options] <script.rb> [--extra-options-for-script]"
+ 
+	opts.separator ""
+	opts.separator "Options:"
+
+		
+	opts.on('-p printer', '--printer=printer', [:flat, :graph, :graph_html],
+					'Select a printer:',
+					'  flat - Prints a flat profile as text (default).',
+					'  graph - Prints a graph profile as text.',
+					'  graph_html - Prints a graph profile as html.') do |printer|
+					
+		case printer
+			when :flat
+				options.printer = RubyProf::FlatPrinter
+			when :graph
+				options.printer = RubyProf::GraphPrinter
+			when :graph_html
+				options.printer = RubyProf::GraphHtmlPrinter
+		end
+	end
+		
+	opts.on('-m min_percent', '--min_percent=min_percent', Float,
+					'The minimum percent a method must take before ',
+					'  being included in output reports') do |min_percent|
+		options.min_percent = min_percent
+	end
+
+	opts.on('-f path', '--file=path',
+				'Output results to a file instead of standard out.') do |file|
+		options.file = file
+	end
+		
+	opts.on('-c clock_mode', '--clock-mode=clock_mode',
+			[:process, :wall, :cpu],
+			'Select a clock mode:',
+			'  process - Use process time (default).',
+			'  wall - Use wall time.',
+			'  cpu - Use the CPU clock counter',
+			'        (only supported on Pentium and PowerPCs).') do |clock_mode|
+			
+			case
+			when :process
+				options.clock_mode = RubyProf::PROCESS_TIME			
+			when :wall
+				options.clock_mode = RubyProf::WALL_TIME			
+			when :cpu
+				options.clock_mode = RubyProf::CPU_TIME
+			end
+	end
+		
+	opts.on_tail("-h", "--help", "Show help message") do
+			puts opts
+			exit
+	end
+	opts.on_tail("-v", "--version", "Show version") do
+			puts "ruby_prof " + RubyProf::VERSION
+			exit
+	end
+end
+
+begin
+	opts.parse! ARGV
+rescue OptionParser::InvalidOption, OptionParser::InvalidArgument,
+       OptionParser::MissingArgument => e
+	puts opts
+  puts
+  puts e.message
+  exit(-1)
+end
+
+# Make sure the user specified at least one file
+if ARGV.length < 1
+	puts opts
+	puts ""
+	puts "Must specify a script to run"
+  exit(-1)
+end
+
+
+# Install at_exit handler.  It is important that we do this 
+# before loading the scripts so our at_exit handler run
+# *after* any other one that will be installed. 
+
+at_exit {
+  # Stop profiling
+	result = RubyProf.stop
+
+	# Create a printer
+	printer = options.printer.new(result)
+
+	# Get output
+	if options.file
+		File.open(options.file, 'w') do |file|
+			printer.print(file, options.min_percent)
+		end
+	else
+		# Print out results	
+		printer.print(STDOUT, options.min_percent)
+	end
+}
+
+# Now set clock mode
+RubyProf.clock_mode = options.clock_mode
+
+# Get the script we will execute
+script = ARGV.shift
+
+# Start profiling
+RubyProf.start 
+
+# Load the script
+load script