ruby-prof 0.18.0 → 1.0.0

data/lib/ruby-prof/measurement.rb

@@ -0,0 +1,14 @@
+module RubyProf
+  # The Measurement class is a helper class used by RubyProf::MethodInfo to store information about the method.
+  # You cannot create a CallInfo object directly, they are generated while running a profile.
+  class Measurement
+    # :nodoc:
+    def to_s
+      "c: #{called}, tt: #{total_time}, st: #{self_time}"
+    end
+
+    def inspect
+      super + "(#{self.to_s})"
+    end
+  end
+end

data/lib/ruby-prof/method_info.rb

@@ -1,108 +1,78 @@
 # encoding: utf-8
 
 module RubyProf
+  # The MethodInfo class is used to track information about each method that is profiled.
+  # You cannot create a MethodInfo object directly, they are generated while running a profile.
   class MethodInfo
     include Comparable
 
-    def <=>(other)
-      if self.total_time < other.total_time
-        -1
-      elsif self.total_time > other.total_time
-        1
-      elsif self.min_depth < other.min_depth
-        1
-      elsif self.min_depth > other.min_depth
-        -1
-      else
-        self.full_name <=> other.full_name
-      end
+    # Returns the full name of a class. The interpretation of method names is:
+    #
+    # * MyObject#test - An method defined in a class
+    # * <Class:MyObject>#test - A method defined in a singleton class.
+    # * <Module:MyObject>#test - A method defined in a singleton module.
+    # * <Object:MyObject>#test - A method defined in a singleton object.
+    def full_name
+      decorated_class_name = case self.klass_flags
+                             when 0x2
+                               "<Class::#{klass_name}>"
+                             when 0x4
+                               "<Module::#{klass_name}>"
+                             when 0x8
+                               "<Object::#{klass_name}>"
+                             else
+                               klass_name
+                             end
+
+      "#{decorated_class_name}##{method_name}"
     end
 
+    # The number of times this method was called
     def called
-      @called ||= begin
-        call_infos.inject(0) do |sum, call_info|
-          sum + call_info.called
-        end
-      end
+      self.measurement.called
     end
 
+    # The total time this method took - includes self time + wait time + child time
     def total_time
-      @total_time ||= begin
-        call_infos.inject(0) do |sum, call_info|
-          sum += call_info.total_time if !call_info.recursive?
-          sum
-        end
-      end
+      self.measurement.total_time
     end
 
+    # The time this method took to execute
     def self_time
-      @self_time ||= begin
-        call_infos.inject(0) do |sum, call_info|
-          sum += call_info.self_time if !call_info.recursive?
-          sum
-        end
-      end
+      self.measurement.self_time
     end
 
+    # The time this method waited for other fibers/threads to execute
     def wait_time
-      @wait_time ||= begin
-        call_infos.inject(0) do |sum, call_info|
-          sum += call_info.wait_time if !call_info.recursive?
-          sum
-        end
-      end
+      self.measurement.wait_time
     end
 
+    # The time this method's children took to execute
     def children_time
-      @children_time ||= begin
-        call_infos.inject(0) do |sum, call_info|
-          sum += call_info.children_time if !call_info.recursive?
-          sum
-        end
-      end
+      self.total_time - self.self_time - self.wait_time
     end
 
+    # The min call depth of this method
     def min_depth
-      @min_depth ||= call_infos.map(&:depth).min
-    end
-
-    def root?
-      @root ||= begin
-        call_infos.find do |call_info|
-          not call_info.root?
-        end.nil?
-      end
-    end
-
-    def children
-      @children ||= call_infos.map(&:children).flatten
+      @min_depth ||= callers.map(&:depth).min
     end
 
-    def parents
-      @parents ||= call_infos.map(&:parent)
-    end
-
-    def aggregate_parents
-      # group call infos based on their parents
-      groups = self.call_infos.each_with_object({}) do |call_info, hash|
-        key = call_info.parent ? call_info.parent.target : self
-        (hash[key] ||= []) << call_info
-      end
-
-      groups.map do |key, value|
-        AggregateCallInfo.new(value, self)
-      end
-    end
-
-    def aggregate_children
-      # group call infos based on their targets
-      groups = self.children.each_with_object({}) do |call_info, hash|
-        key = call_info.target
-        (hash[key] ||= []) << call_info
-      end
-
-      groups.map do |key, value|
-        AggregateCallInfo.new(value, self)
+    # :enddoc:
+    def <=>(other)
+      if other == nil
+        -1
+      elsif self.full_name == other.full_name
+        0
+      elsif self.total_time < other.total_time
+        -1
+      elsif self.total_time > other.total_time
+        1
+      elsif self.min_depth < other.min_depth
+        1
+      elsif self.min_depth > other.min_depth
+        -1
+      else
+        self.full_name <=> other.full_name
       end
     end
 
@@ -110,12 +80,11 @@ module RubyProf
       "#{self.full_name} (c: #{self.called}, tt: #{self.total_time}, st: #{self.self_time}, wt: #{wait_time}, ct: #{self.children_time})"
     end
 
-    # remove method from the call graph. should not be called directly.
+    # Remove method from the call graph. should not be called directly.
     def eliminate!
       # $stderr.puts "eliminating #{self}"
-      call_infos.each{ |call_info| call_info.eliminate! }
-      call_infos.clear
+      callers.each{ |call_info| call_info.eliminate! }
+      callers.clear
     end
-
   end
 end

data/lib/ruby-prof/printers/abstract_printer.rb

@@ -1,7 +1,14 @@
 # encoding: utf-8
 
 module RubyProf
+  # This is the base class for all Printers. It is never used directly.
   class AbstractPrinter
+    # :stopdoc:
+    def self.needs_dir?
+      false
+    end
+    # :startdoc:
+
     # Create a new printer.
     #
     # result should be the output generated from a profiling run
@@ -10,74 +17,56 @@ module RubyProf
       @output = nil
     end
 
-    # Specify print options.
-    #
-    # options - Hash table
-    #   :min_percent - Number 0 to 100 that specifes the minimum
-    #                  %self (the methods self time divided by the
-    #                  overall total time) that a method must take
-    #                  for it to be printed out in the report.
-    #                  Default value is 0.
-    #
-    #   :print_file  - True or false. Specifies if a method's source
-    #                  file should be printed.  Default value if false.
-    #
-    #   :sort_method - Specifies method used for sorting method infos.
-    #                  Available values are :total_time, :self_time,
-    #                  :wait_time, :children_time
-    #                  Default value is :total_time
-    #    :editor_uri - Specifies editor uri scheme used for opening files
-    #                  e.g. :atm or :mvim. For OS X default is :txmt.
-    #                  Pass false to print bare filenames.
-    #                  Use RUBY_PROF_EDITOR_URI environment variable to override.
-    def setup_options(options = {})
-      @options = options
-    end
-
+    # Returns the min_percent of total time a method must take to be included in a profiling report
     def min_percent
       @options[:min_percent] || 0
     end
 
-    def print_file
-      @options[:print_file] || false
+    # Returns the time format used to show when a profile was run
+    def time_format
+      '%A, %B %-d at %l:%M:%S %p (%Z)'
     end
 
+    # Returns how profile data should be sorted
     def sort_method
-      @options[:sort_method] || :total_time
-    end
-
-    def editor_uri
-      if ENV.key?('RUBY_PROF_EDITOR_URI')
-        ENV['RUBY_PROF_EDITOR_URI'] || false
-      elsif @options.key?(:editor_uri)
-        @options[:editor_uri]
-      else
-        RUBY_PLATFORM =~ /darwin/ ? 'txmt' : false
-      end
-    end
-
-    def method_name(method)
-      name = method.full_name
-      if print_file
-        name += " (#{method.source_file}:#{method.line}}"
-      end
-      name
+      @options[:sort_method]
     end
 
-    # Print a profiling report to the provided output.
+    # Prints a report to the provided output.
     #
     # output - Any IO object, including STDOUT or a file.
     # The default value is STDOUT.
     #
-    # options - Hash of print options.  See #setup_options
-    # for more information.  Note that each printer can
+    # options - Hash of print options. Note that each printer can
     # define its own set of options.
+    #
+    #   :min_percent - Number 0 to 100 that specifes the minimum
+    #                  %self (the methods self time divided by the
+    #                  overall total time) that a method must take
+    #                  for it to be printed out in the report.
+    #                  Default value is 0.
+    #
+    #   :sort_method - Specifies method used for sorting method infos.
+    #                  Available values are :total_time, :self_time,
+    #                  :wait_time, :children_time
+    #                  Default value is :total_time
     def print(output = STDOUT, options = {})
       @output = output
       setup_options(options)
       print_threads
     end
 
+    # :nodoc:
+    def setup_options(options = {})
+      @options = options
+    end
+
+    def method_location(method)
+      if method.source_file
+        "#{method.source_file}:#{method.line}"
+      end
+    end
+
     def print_threads
       @result.threads.each do |thread|
         print_thread(thread)
@@ -91,14 +80,39 @@ module RubyProf
     end
 
     def print_header(thread)
+      @output << "Measure Mode: %s\n" % RubyProf.measure_mode_string
+      @output << "Thread ID: %d\n" % thread.id
+      @output << "Fiber ID: %d\n" % thread.fiber_id unless thread.id == thread.fiber_id
+      @output << "Total: %0.6f\n" % thread.total_time
+      @output << "Sort by: #{sort_method}\n"
+      @output << "\n"
+      print_column_headers
     end
 
-    def print_footer(thread)
+    def print_column_headers
     end
 
-    # whether this printer need a :path option pointing to a directory
-    def self.needs_dir?
-      false
+    def print_footer(thread)
+      @output << <<~EOT
+      
+        * recursively called methods
+
+        Columns are:
+
+          %self     - The percentage of time spent in this method, derived from self_time/total_time.
+          total     - The time spent in this method and its children.
+          self      - The time spent in this method.
+          wait      - The amount of time this method waited for other threads.
+          child     - The time spent in this method's children.
+          calls     - The number of times this method was called.
+          name      - The name of the method.
+          location  - The location of the method.
+
+        The interpretation of method names is:
+
+          * MyObject#test - An instance method "test" of the class "MyObject"
+          * <Object:MyObject>#test - The <> characters indicate a method on a singleton class.
+      EOT
     end
   end
 end

data/lib/ruby-prof/printers/call_info_printer.rb

@@ -4,7 +4,15 @@ module RubyProf
   # Prints out the call graph based on CallInfo instances. This
   # is mainly for debugging purposes as it provides access into
   # into RubyProf's internals.
-
+  #
+  # To use the printer:
+  #
+  #   result = RubyProf.profile do
+  #     [code to profile]
+  #   end
+  #
+  #   printer = RubyProf::CallInfoPrinter.new(result)
+  #   printer.print(STDOUT)
   class CallInfoPrinter < AbstractPrinter
     TIME_WIDTH = 0
 
@@ -19,7 +27,7 @@ module RubyProf
     end
 
     def print_methods(thread)
-      visitor = CallInfoVisitor.new(thread.top_call_infos)
+      visitor = CallInfoVisitor.new(thread.root_methods)
 
       visitor.visit do |call_info, event|
         if event == :enter
@@ -31,11 +39,13 @@ module RubyProf
           @output << "wt:#{sprintf("%#{TIME_WIDTH}.2f", call_info.wait_time)}, "
           @output << "ct:#{sprintf("%#{TIME_WIDTH}.2f", call_info.children_time)}, "
           @output << "call:#{call_info.called}, "
-          @output << "rec:#{call_info.recursive?}"
           @output << ")"
           @output << "\n"
         end
       end
     end
+
+    def print_footer(thread)
+    end
   end
 end

data/lib/ruby-prof/printers/call_stack_printer.rb

@@ -3,10 +3,21 @@
 require 'erb'
 require 'fileutils'
 require 'base64'
+require 'set'
 
 module RubyProf
-  # prints a HTML visualization of the call tree
-  class CallStackPrinter < AbstractPrinter
+  # Prints a HTML visualization of the call tree.
+  #
+  # To use the printer:
+  #
+  #   result = RubyProf.profile do
+  #     [code to profile]
+  #   end
+  #
+  #   printer = RubyProf::CallStackPrinter.new(result)
+  #   printer.print(STDOUT)
+
+class CallStackPrinter < AbstractPrinter
     include ERB::Util
 
     # Specify print options.
@@ -18,9 +29,6 @@ module RubyProf
     #                  for it to be printed out in the report.
     #                  Default value is 0.
     #
-    #   :print_file  - True or false. Specifies if a method's source
-    #                  file should be printed.  Default value if false.
-    #
     #   :threshold   - a float from 0 to 100 that sets the threshold of
     #                  results displayed.
     #                  Default value is 1.0
@@ -35,14 +43,9 @@ module RubyProf
     #
     #   :application - a String to overide the name of the application,
     #                  as it appears on the report.
-    #
-    #    :editor_uri - Specifies editor uri scheme used for opening files
-    #                  e.g. :atm or :mvim. For OS X default is :txmt.
-    #                  Use RUBY_PROF_EDITOR_URI environment variable to overide.
     def print(output = STDOUT, options = {})
       @output = output
       setup_options(options)
-      @editor = editor_uri
       if @graph_html = options.delete(:graph)
         @graph_html = "file://" + @graph_html if @graph_html[0]=="/"
       end
@@ -64,29 +67,29 @@ module RubyProf
         thread.methods.each do |m|
           # $stderr.print m.dump
           next unless m.root?
-          m.call_infos.each do |ci|
-            next unless ci.root?
-            print_stack ci, thread.total_time
+          m.callers.each do |call_info|
+            visited = Set.new
+            print_stack(visited, call_info, thread.total_time)
           end
         end
         @output.print "</ul>"
       end
 
       print_footer
-
     end
 
-    def print_stack(call_info, parent_time)
+    def print_stack(visited, call_info, parent_time)
       total_time = call_info.total_time
       percent_parent = (total_time/parent_time)*100
       percent_total = (total_time/@overall_time)*100
       return unless percent_total > min_percent
       color = self.color(percent_total)
-      kids = call_info.children
+      kids = call_info.target.callees
       visible = percent_total >= threshold
       expanded = percent_total >= expansion
       display = visible ? "block" : "none"
       @output.print "<li class=\"color#{color}\" style=\"display:#{display}\">"
+
       if kids.empty?
         @output.print "<a href=\"#\" class=\"toggle empty\" ></a>"
       else
@@ -95,14 +98,21 @@ module RubyProf
         @output.print "<a href=\"#\" class=\"toggle #{image}\" ></a>"
       end
       @output.printf "<span> %4.2f%% (%4.2f%%) %s %s</span>\n", percent_total, percent_parent, link(call_info), graph_link(call_info)
+
+      if visited.include?(call_info)
+        return
+      else
+        visited << call_info
+      end
+
       unless kids.empty?
         if expanded
           @output.print "<ul>"
         else
           @output.print '<ul style="display:none">'
         end
-        kids.sort_by{|c| -c.total_time}.each do |callinfo|
-          print_stack callinfo, total_time
+        kids.sort_by{|c| -c.total_time}.each do |child_call_info|
+          print_stack(visited, child_call_info, total_time)
         end
         @output.print "</ul>"
       end
@@ -116,22 +126,16 @@ module RubyProf
 
     def link(call_info)
       method = call_info.target
-      file = File.expand_path(method.source_file)
-      if file =~ /\/ruby_runtime$/
+      if method.source_file.nil?
         h(name(call_info))
       else
-        if @editor
-          "<a href=\"#{@editor}://" \
-          "open?url=file://#{file}&line=#{method.line}\">" \
-          "#{h(name(call_info))}</a>"
-        else
-          "<a href=\"file://#{file}##{method.line}\">#{h(name(call_info))}</a>"
-        end
+        file = File.expand_path(method.source_file)
+       "<a href=\"file://#{file}##{method.line}\">#{h(name(call_info))}</a>"
       end
     end
 
     def graph_link(call_info)
-      total_calls = call_info.target.call_infos.inject(0){|t, ci| t += ci.called}
+      total_calls = call_info.target.callers.inject(0){|t, ci| t += ci.called}
       href = "#{@graph_html}##{method_href(call_info.target)}"
       totals = @graph_html ? "<a href='#{href}'>#{total_calls}</a>" : total_calls.to_s
       "[#{call_info.called} calls, #{totals} total]"