minstrel 0.2.20110428124038 → 0.3.0

data/lib/minstrel.rb

@@ -1,282 +1,226 @@
 # Wrap method calls for a class of your choosing.
 # Example:
-# instrument = Minstrel::Instrument.new()
-# instrument.wrap(String) do |point, klass, method, *args|
-#   ...
-# end
 #
-#  * point is either :enter or :exit depending if this function is about to be
-#    called or has finished being called.
-#  * klass is the class object (String, etc)
-#  * method is the method (a Symbol)
-#  * *args is the arguments passed
+#     instrument = Minstrel::Instrument.new()
+#     instrument.observe(class_or_method) { |event| ... }
 #
-# You can also wrap from the command-line
+# The 'event' is a Minstrel::Event.
 #
-# RUBY_INSTRUMENT=comma_separated_classnames ruby -rminstrel ./your/program.rb
+# You can also wrap from the command-line
+#     RUBY_INSTRUMENT=comma_separated_classnames ruby -rminstrel ./your/program.rb
 #
 
-require "set"
-
-module Minstrel; class Instrument
-  attr_accessor :counter
-
-  class << self
-    @@deferred_wraps = {}
-    @@deferred_method_wraps = {}
-    @@wrapped = Set.new
-  end
-
-  # Put methods we must not be wrapping here.
-  DONOTWRAP = {
-    "Minstrel::Instrument" => Minstrel::Instrument.instance_methods.collect { |m| m.to_sym },
-    "Object" => [ :to_sym, :respond_to?, :send, :java_send, :method, :java_method,
-                  :ancestors, :inspect, :to_s, :instance_eval, :instance_exec,
-                  :class_eval, :class_exec, :module_eval, :module_exec],
-  }
-
-  # Wrap a class's instance methods with your block.
-  # The block will be called with 4 arguments, and called
-  # before and after the original method.
-  # Arguments:
-  #   * point - the point (symbol, :entry or :exit) of call,
-  #   * this - the object instance in scope (use 'this.class' for the class)
-  #   * method - the method (symbol) being called
-  #   * *args - the arguments (array) passed to this method.
-  def wrap(klass, method_to_wrap=nil, &block)
-    return true if @@wrapped.include?(klass)
-    instrumenter = self # save 'self' for scoping below
-    @@wrapped << klass
-
-    ancestors = klass.ancestors.collect {|k| k.to_s } 
-    if ancestors.include?("Exception")
-      return true
+module Minstrel; end
+
+class Minstrel::Event
+  attr_accessor :action
+  attr_accessor :file
+  attr_accessor :line
+  attr_accessor :method
+  attr_accessor :binding
+  attr_accessor :class
+  attr_accessor :args_hash
+  attr_accessor :args_order
+  attr_accessor :timestamp
+
+  # Duration is only valid for 'return' or 'c-return' events
+  attr_accessor :duration
+
+  # The call stack depth of this event
+  attr_accessor :depth
+
+  public
+  def initialize(action, file, line, method, binding, klass)
+    @action = action
+    @file = file
+    @line = line
+    @method = method
+    @binding = binding
+    @class = klass
+    @timestamp = Time.now
+
+    if ["c-call", "call"].include?(@action)
+      @args_hash = {}
+      @args_order = eval('local_variables', binding)
+
+      # In ruby 1.9, local_variables returns an array of symbols, not strings.
+      @args_order.collect { |v| @args_hash[v] = eval(v.to_s, binding) }
     end
-    puts "Wrapping #{klass.class} #{klass}" if $DEBUG
 
-    # Wrap class instance methods (like File#read)
-    klass.instance_methods.each do |method|
-      next if !method_to_wrap.nil? and method != method_to_wrap
+    @block_given = eval('block_given?', @binding)
+  end # def initialize
+
+  # Get the call args as an array in-order
+  public
+  def args
+    return nil unless @args_order
+    return @args_order.collect { |v| @args_hash[v] }
+  end # def args
+
+  public
+  def use_related_event(event)
+    @args_order = event.args_order
+    @args_hash = event.args_hash
+    @block_given = event.block_given?
+    @duration = @timestamp - event.timestamp
+  end # def use_related_event
+
+  # Is this event a method entry?
+  public
+  def entry?
+    return ["c-call", "call"].include?(action)
+  end # def entry?
+
+  # Is this event a method return?
+  public
+  def exit?
+    return ["c-return", "return"].include?(action)
+  end # def exit?
+
+  # Was there a block given to this method?
+  public
+  def block_given?
+    @block_given
+  end # def block_given ?
+
+  public
+  def symbol
+    case @action
+      when "c-call", "call" ; return "=>"
+      when "c-return", "return" ; return "<="
+      when "raise"; return "<E"
+      else return " +"
+    end
+  end # def symbol
 
-      method = method.to_sym
+  public
+  def to_s
+    return "#{"  " * @depth}#{symbol} #{@class.to_s}##{@method}(#{args.inspect}) #{block_given? ? "{ ... }" : ""} (thread=#{Thread.current}) #{@duration.nil? ? "" : sprintf("(%.5f seconds)", @duration)}"
+  end # def to_s
 
-      # If we shouldn't wrap a certain class method, skip it.
-      skip = false
-      (ancestors & DONOTWRAP.keys).each do |key|
-        if DONOTWRAP[key].include?(method)
-          skip = true 
-          break
-        end
-      end
-      if skip
-        #puts "Skipping #{klass}##{method} (do not wrap)"
-        next
-      end
+end # class Minstrel::Event
 
-      klass.class_eval do
-        orig_method = "#{method}_original(wrapped)".to_sym
-        orig_method_proc = klass.instance_method(method)
-        alias_method orig_method, method
-        #block.call(:wrap, klass, method)
-        puts "Wrapping #{klass.name}##{method} (method)" if $DEBUG
-        define_method(method) do |*args, &argblock|
-          exception = false
-          block.call(:enter, self, method, *args)
-          begin
-            # TODO(sissel): Not sure which is better:
-            # * UnboundMethod#bind(self).call(...)
-            # * self.method(orig_method).call(...)
-            val = orig_method_proc.bind(self).call(*args, &argblock)
-            #m = self.method(orig_method)
-            #val = m.call(*args, &argblock)
-          rescue => e
-            exception = e
-          end
-          if exception
-            # TODO(sissel): Include the exception
-            block.call(:exit_exception, self, method, *args)
-            raise e if exception
-          else
-            # TODO(sissel): Include the return value
-            block.call(:exit, self, method, *args)
-          end
-          return val
-        end # define_method(method)
-      end # klass.class_eval
-    end # klass.instance_methods.each
+class Minstrel::Instrument
+  attr_accessor :counter
 
-    # Wrap class methods (like File.open)
-    klass.methods.each do |method|
-      next if !method_to_wrap.nil? and method != method_to_wrap
-      method = method.to_sym
-      # If we shouldn't wrap a certain class method, skip it.
-      skip = false
-      ancestors = klass.ancestors.collect {|k| k.to_s} 
-      (ancestors & DONOTWRAP.keys).each do |key|
-        if DONOTWRAP[key].include?(method)
-          skip = true 
-          #break
-        end
-      end
+  public
+  def self.singleton
+    @minstrel ||= Minstrel::Instrument.new
+  end # def self.singleton
 
-      # Doubly-ensure certain methods are not wrapped.
-      # Some classes like "Timeout" do not have ancestors.
-      if DONOTWRAP["Object"].include?(method)
-        #puts "!! Skipping #{klass}##{method} (do not wrap)"
-        skip = true
-      end
+  public
+  def initialize
+    @observe = []
+    @stack = Hash.new { |h,k| h[k] = [] } # per thread
+  end # def initialize
 
-      if skip
-        puts "Skipping #{klass}##{method} (do not wrap, not safe)" if $DEBUG
-        next
-      end
+  public
+  def stack
+    return @stack
+  end
 
-      klass.instance_eval do
-        orig_method = "#{method}_original(classwrapped)".to_sym
-        (class << self; self; end).instance_eval do
-          begin
-            alias_method orig_method, method.to_sym
-          rescue NameError => e
-            # No such method, strange but true.
-            orig_method = self.method(method.to_sym)
+  public
+  def observe(thing=nil, &block)
+    if !thing.nil?
+      # Is thing a class name?
+      @observe << lambda do |event| 
+        if class?(thing)
+          if event.class.to_s == thing.to_s
+            block.call(event) 
           end
-          method = method.to_sym
-          #puts "Wrapping #{klass.name}.#{method} (classmethod)"
-          define_method(method) do |*args, &argblock|
-            block.call(:class_enter, self, method, *args)
-            exception = false
-            begin
-              if orig_method.is_a?(Symbol)
-                val = send(orig_method, *args, &argblock)
-              else
-                val = orig_method.call(*args, &argblock)
-              end
-            rescue => e
-              exception = e
-            end
-            if exception
-              block.call(:class_exit_exception, self, method, *args)
-              raise e if exception
-            else
-              block.call(:class_exit, self, method, *args)
-            end
-            return val
+        else
+          # assume it's a method?
+          #p :observe => nil, :class => thing, :is => class?(thing)
+          klass, method = thing.split(/[.#]/, 2)
+          if (event.class.to_s == klass and event.method = method.to_sym)
+            block.call(event)
           end
         end
-        #block.call(:class_wrap, self, method, self.method(method))
-      end # klass.instance_eval
-    end # klass.instance_methods.each
-
-    return true
-  end # def wrap
-
-  def wrap_classname(klassname, &block)
-    begin
-      klass = eval(klassname)
-      wrap(klass, &block) 
-      return true
-    rescue NameError => e
-      @@deferred_wraps[klassname] = block
-    end
-    return false
-  end
-
-  def wrap_method(fullname, &block)
-    puts "Want to wrap #{fullname}" if $DEBUG
-    begin
-      klassname, method = fullname.split(/[#.]/, 2)
-      klass = eval(klassname)
-      wrap(klass, method, &block)
-      return true
-    rescue NameError => e
-      @@deferred_method_wraps[fullname] = block
-      return false
-    end
-  end # def wrap_method
-
-  def wrap_all(&block)
-    @@deferred_wraps[:all] = block
-    ObjectSpace.each_object do |obj|
-      next unless obj.is_a?(Class)
-      wrap(obj, &block)
-    end
-  end
-
-  def self.wrap_require
-    Kernel.class_eval do
-      alias_method :old_require, :require
-      def require(*args)
-        return Minstrel::Instrument::instrumented_loader(:require, *args)
       end
+    elsif block_given?
+      @observe << block
+    else
+      raise ArgumentError.new("No block given.")
     end
-  end
+  end # def observe
 
-  def self.wrap_load
-    Kernel.class_eval do
-      alias_method :old_load, :load
-      def load(*args)
-        return Minstrel::Instrument::instrumented_loader(:load, *args)
-      end
+  # Is the thing here a class?
+  # Can be a string name of a class or a class object
+  private
+  def class?(thing)
+    #p :method => "class?", :thing => thing, :class => thing.is_a?(Class), :foo => thing.inspect
+    begin
+      return true if thing.is_a?(Class)
+      return false if (thing.is_a?(String) and thing.include?("#"))
+      obj = eval(thing)
+      return obj.is_a?(Class)
+    rescue => e
+      false
     end
-  end
-
-  def self.instrumented_loader(method, *args)
-    ret = self.send(:"old_#{method}", *args)
-    if @@deferred_wraps.include?(:all)
-      # try to wrap anything new that is not wrapped
-      wrap_all(@@deferred_wraps[:all])
-    else
-      # look for deferred class wraps
-      klasses = @@deferred_wraps.keys
-      klasses.each do |klassname|
-        if @@deferred_wraps.include?("ALL")
-          all = true
-        end
-        block = @@deferred_wraps[klassname]
-        instrument = Minstrel::Instrument.new
-        if instrument.wrap_classname(klassname, &block)
-          $stderr.puts "Wrap of #{klassname} successful"
-          @@deferred_wraps.delete(klassname) if !all
+  end # def class?
+
+  # Activate tracing
+  public
+  def enable
+    set_trace_func(Proc.new { |*args| trace_callback(*args) })
+  end # def enable
+
+  # Disable tracing
+  public
+  def disable
+    set_trace_func(nil)
+  end # def disable
+
+  # This method is invoked by the ruby tracer
+  private
+  def trace_callback(action, file, line, method, binding, klass)
+    begin
+      event = Minstrel::Event.new(action, file, line, method, binding, klass)
+      # At the time of "c-call" there's no other local variables other than
+      # the method arguments. Pull the args out of binding
+      #event.args = eval('local_variables.collect { |v| "(#{v}) #{v.inspect}" }', binding)
+      if ["c-call", "call"].include?(action)
+        @stack[Thread.current].push event
+        event.depth = @stack[Thread.current].size
+      elsif ["c-return", "return", "raise"].include?(action)
+        # TODO(sissel): validate top of stack looks right?
+        event.depth = @stack[Thread.current].size
+        entry_event = @stack[Thread.current].pop
+        if !entry_event.nil?
+          event.use_related_event(entry_event)
         end
+      else
+        event.depth = @stack[Thread.current].size
       end
 
-      klassmethods = @@deferred_method_wraps.keys
-      klassmethods.each do |fullname|
-        block = @@deferred_method_wraps[fullname]
-        instrument = Minstrel::Instrument.new
-        if instrument.wrap_method(fullname, &block)
-          $stderr.puts "Wrap of #{fullname} successful"
-          @@deferred_method_wraps.delete(fullname)
-        end
-      end
+      # Call any observers
+      @observe.each { |callback| callback.call(event) }
+    rescue => e
+      $stderr.puts "Exception in trace_callback: #{e}"
+      $stderr.puts e.backtrace
+      raise e
     end
-    return ret
-  end
-end; end # class Minstrel::Instrument
-
-Minstrel::Instrument.wrap_require
-Minstrel::Instrument.wrap_load
+  end # def trace_callback
+end # class Minstrel::Instrument
 
 # Provide a way to instrument a class using the command line:
 # RUBY_INSTRUMENT=String ruby -rminstrel ./your/program
 if ENV["RUBY_INSTRUMENT"]
   klasses = ENV["RUBY_INSTRUMENT"].split(",")
 
-  callback = proc do |point, this, method, *args|
-    puts "#{point} #{this.class.to_s}##{method}(#{args.inspect}) (thread=#{Thread.current}, self=#{this.inspect})"
+  callback = proc do |event|
+    # Only show entry or exits
+    next unless (event.entry? or event.exit?)
+    puts event
   end
+
   instrument = Minstrel::Instrument.new 
   if klasses.include?(":all:")
-    instrument.wrap_all(&callback)
+    instrument.observe(&callback)
   else
     klasses.each do |klassname|
-      if klassname =~ /[#.]/ # Someone's asking for a specific method to wrap
-        # This will wrap one method as indicated by: ClassName#method
-        # TODO(sissel): Maybe also allow ModuleName::method
-        instrument.wrap_method(klassname, &callback) 
-      else
-        instrument.wrap_classname(klassname, &callback) 
-      end
+      instrument.observe(klassname, &callback)
     end # klasses.each
   end 
+  instrument.enable
 end # if ENV["RUBY_INSTRUMENT"]

data/minstrel.gemspec

@@ -6,9 +6,8 @@ Gem::Specification.new do |spec|
     "./minstrel.gemspec",
   ]
 
-  rev = Time.now.strftime("%Y%m%d%H%M%S")
   spec.name = "minstrel"
-  spec.version = "0.2.#{rev}"
+  spec.version = "0.3.0"
   spec.summary = "minstrel - a ruby instrumentation tool"
   spec.description = "Instrument class methods"
   spec.files = files

metadata

@@ -1,71 +1,50 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: minstrel
-version: !ruby/object:Gem::Version 
-  hash: 40220856248091
-  prerelease: false
-  segments: 
-  - 0
-  - 2
-  - 20110428124038
-  version: 0.2.20110428124038
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Jordan Sissel
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-04-28 00:00:00 -07:00
-default_executable: 
+date: 2012-01-21 00:00:00.000000000 Z
 dependencies: []
-
 description: Instrument class methods
 email: jls@semicomplete.com
-executables: 
+executables:
 - minstrel
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - ./lib/minstrel.rb
 - ./README.textile
 - ./minstrel.gemspec
 - bin/minstrel
-has_rdoc: true
 homepage: https://github.com/jordansissel/ruby-minstrel
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: minstrel - a ruby instrumentation tool
 test_files: []
-