rb-trace 0.2

data/lib/trace_mod.rb

@@ -0,0 +1,207 @@
+require_relative '../ext/trace'
+
+# A module for interfacing with Kernel::set_trace which adds
+# filtering of events inside Ruby (as opposed to inside your trace
+# hook which is slower).
+module Trace
+
+
+  unless defined?(NO_EVENT_MASK)
+    NO_EVENT_MASK        = 0x0000   
+    # Event masks from +ruby.h+
+    LINE_EVENT_MASK      = 0x0001
+    CLASS_EVENT_MASK     = 0x0002
+    END_EVENT_MASK       = 0x0004
+    CALL_EVENT_MASK      = 0x0008
+    RETURN_EVENT_MASK    = 0x0010
+    C_CALL_EVENT_MASK    = 0x0020
+    C_RETURN_EVENT_MASK  = 0x0040
+    RAISE_EVENT_MASK     = 0x0080
+    INSN_EVENT_MASK      = 0x0100
+    BRKPT_EVENT_MASK     = 0x0200
+    ALL_EVENT_MASKS      = (0xffff & ~INSN_EVENT_MASK)
+    VM_EVENT_MASK        = 0x10000
+    SWITCH_EVENT_MASK    = 0x20000
+    COVERAGE_EVENT_MASK  = 0x40000
+    
+    # Events that will trigger if you don't specify any
+    DEFAULT_EVENT_MASK   = 
+      BRKPT_EVENT_MASK    |
+      CALL_EVENT_MASK     |
+      CLASS_EVENT_MASK    |
+      C_CALL_EVENT_MASK   |
+      C_RETURN_EVENT_MASK |
+      END_EVENT_MASK      |
+      LINE_EVENT_MASK     |
+      RAISE_EVENT_MASK    |
+      RETURN_EVENT_MASK 
+    
+    
+    # Symbols we use to represent the individual bits inside a Fixnum bitmask
+    EVENT2MASK = {
+      :brkpt    => BRKPT_EVENT_MASK,
+      :c_call   => C_CALL_EVENT_MASK,
+      :c_return => C_RETURN_EVENT_MASK,
+      :call     => CALL_EVENT_MASK,
+      :class    => CLASS_EVENT_MASK,
+      :coverage => COVERAGE_EVENT_MASK,
+      :end      => END_EVENT_MASK,
+      :insn     => INSN_EVENT_MASK,
+      :line     => LINE_EVENT_MASK,
+      :raise    => RAISE_EVENT_MASK,
+      :return   => RETURN_EVENT_MASK,
+      :switch   => SWITCH_EVENT_MASK,
+      :vm       => VM_EVENT_MASK
+    }
+
+    EVENTS = EVENT2MASK.keys.sort
+  end
+
+  # Convert +events+ into a Fixnum bitmask used internally by Ruby.
+  # Parameter +events+ should be Enumerable and each element should
+  # either be a Fixnum mask value or something that can be converted
+  # to a symbol. If the latter, the case is not important as we'll
+  # downcase the string representation.
+  def events2bitmask(events)
+    bitmask = NO_EVENT_MASK
+    bad_events = []
+    events.each do |event|
+      nextbit = nil
+      if event.is_a?(Fixnum)
+        # Assume a bit mask
+        nextbit = event
+      elsif event.respond_to?(:to_sym)
+        # Assume an event name
+        sym = event.to_sym.to_s.downcase.to_sym
+        nextbit = EVENT2MASK[sym] if EVENT2MASK.member?(sym)
+      end
+      if nextbit
+        bitmask |= nextbit
+      else
+        bad_events << event
+      end
+    end
+    return bitmask, bad_events
+  end
+  module_function :events2bitmask
+
+  # Convert Fixnum +bitmask+ used internally by Ruby, into an Array of
+  # event names.
+  def bitmask2events(bitmask)
+    mask = []
+    EVENT2MASK.each do |key, value|
+      mask << key if (value & bitmask) != 0
+    end
+    return mask
+  end
+  module_function :bitmask2events
+
+  def convert_event_mask(mask_arg)
+    if mask_arg.is_a?(Fixnum)
+      event_mask = mask_arg
+    elsif mask_arg.kind_of?(Enumerable)
+      event_mask, bad_events = events2bitmask(mask_arg)
+      raise ArgumentError, "Bad set elements: #{bad_events.inspect}" unless
+        bad_events.empty?
+    else
+      raise ArgumentError, "Bad set mask arg: #{mask_arg}"
+    end
+    event_mask
+  end
+  module_function :convert_event_mask
+
+  # Return a list of the global event masks in effect
+  def event_masks
+    RubyVM::TraceHook::trace_hooks.map do |hook|
+      hook.event_mask
+    end
+  end
+  module_function :event_masks
+
+  # Set event masks
+  def event_masks=(mask_arg)
+    RubyVM::TraceHook::trace_hooks.map do |hook|
+      event_mask = convert_event_mask(mask_arg)
+      hook.event_mask = event_mask
+    end
+  end
+  module_function :'event_masks='
+
+  # Replacement for Kernel::set_trace We allow for a more flexible
+  # event mask parameters to be set.
+  def add_trace_func(*args)
+    if args.size > 3 or args.size < 1
+      raise ArgumentError, "wrong number of arguments (#{args.size} for 1..2)"
+    end
+    proc, mask_arg = args
+    if proc.nil? 
+      if args.size != 1
+        raise ArgumentError, 
+        "When first argument (Proc) is nil, there should be only one argument"
+      end
+      return Kernel.set_trace_func(proc)
+    elsif mask_arg.nil?
+      Kernel.add_trace_func(proc)
+    else # args.size == 2
+      event_mask = convert_event_mask(mask_arg)
+      Kernel.add_trace_func(proc, event_mask)
+    end
+  end
+  module_function :add_trace_func
+
+  # Replacement for Kernel::set_trace We allow for a more flexible
+  # event mask parameters to be set.
+  def set_trace_func(*args)
+    if args.size > 3 or args.size < 1
+      raise ArgumentError, "wrong number of arguments (#{args.size} for 1..2)"
+    end
+    proc, mask_arg = args
+    if proc.nil? 
+      if args.size != 1
+        raise ArgumentError, 
+        "When first argument (Proc) is nil, there should be only one argument"
+      end
+      return Kernel.set_trace_func(proc)
+    elsif mask_arg.nil?
+      Kernel.set_trace_func(proc)
+    else # args.size == 2
+      event_mask = convert_event_mask(mask_arg)
+      Kernel.set_trace_func(proc, event_mask)
+    end
+  end
+  module_function :set_trace_func
+end
+
+if __FILE__ == $0
+  # Demo it
+  include Trace
+  require 'set'
+  mask, unhandled = events2bitmask([LINE_EVENT_MASK, CLASS_EVENT_MASK])
+  p bitmask2events(mask)
+  p [mask, unhandled]
+  p events2bitmask(Set.new([LINE_EVENT_MASK, CLASS_EVENT_MASK]))
+  p events2bitmask(['LINE', 'Class'])
+  p events2bitmask(Set.new(['LINE', 'Class']))
+  p events2bitmask([:foo, 'bar'])
+  p events2bitmask(['C call', ['bar']])
+  p events2bitmask(['C call', ['bar']])
+  def foo # :nodoc:
+  end 
+  Trace::set_trace_func(Proc.new {|e, tf| p e}, [:call, :return])
+  foo
+  Trace::event_masks.each { |m| print "event mask: 0x%x\n" % m }
+  Trace::event_masks = [:call]
+  p '=' * 40
+  foo
+  Trace::event_masks.each { |m| print "event mask: 0x%x\n" % m }
+  p '=' * 40
+  Trace::set_trace_func(Proc.new {|e, tf| p e})
+  Trace::event_masks.each { |m| print "event mask: 0x%x\n" % m }
+  foo
+  Trace::set_trace_func(nil)
+  p '=' * 40
+  foo
+  p '=' * 40
+  Trace::event_masks.each { |m| print "event mask: 0x%x\n" % m }
+  
+end

data/lib/tracefilter.rb

@@ -0,0 +1,228 @@
+require 'set'
+# require '/src/external-vcs/rb-threadframe/ext/thread_frame'
+require 'thread_frame'
+require_relative 'trace_mod'
+
+module Trace
+
+  # A class that can be used to test whether certain methods should be
+  # excluded.  We also convert the hook call to pass a threadframe and
+  # an event rather than event and those other 5 parameters.
+  class Filter
+
+    attr_reader :excluded
+    attr_reader :hook_proc
+
+    def initialize(excluded_meths = [])
+      excluded_meths = excluded_meths.select{|fn| valid_meth?(fn)}
+      excluded_meths << self.method(:set_trace_func).to_s
+      @excluded = Set.new(excluded_meths.map{|m| m.to_s})
+    end
+
+    # +fn+ should be a RubyVM::ThreadFrame object or a Proc which has an
+    # instruction sequence
+    def valid_meth?(fn)
+      fn.is_a?(Method)
+    end
+
+    # Add +meth+ to list of trace filters.
+    def <<(meth)
+      if valid_meth?(meth)
+        @excluded << meth.to_s
+        return true
+      else
+        return false
+      end
+    end
+
+    # Null out list of excluded methods
+    def clear
+      @excluded = Set.new
+    end
+
+    # Returns +true+ if +meth+ is a member of the trace filter set.
+    def member?(meth)
+      if valid_meth?(meth)
+        @excluded.member?(meth.to_s)
+      else
+        false
+      end
+    end
+
+    # Remove +meth+ from the list of functions to include.
+    def remove(meth)
+      return nil unless valid_meth?(meth)
+      @excluded -= [meth.to_s]
+    end
+
+    # A shim to convert between older-style trace hook call to newer
+    # style trace hook using RubyVM::ThreadFrame. Methods stored in 
+    # @+excluded+ are ignored.
+    def trace_hook(event, file, line, id, binding, klass)
+      tf = RubyVM::ThreadFrame::current.prev
+
+      # FIXME: Clean this mess up. And while your at it, understand
+      # what's going on better.
+      tf_check = tf
+
+      while %w(BLOCK IFUNC CFUNC).member?(tf_check.type) do 
+        tf_check = tf_check.prev 
+      end
+      return unless tf_check
+
+      begin 
+        if tf_check.method && !tf_check.method.empty?
+          meth_name = tf_check.method.gsub(/^.* in /, '')
+          meth = eval("self.method(:#{meth_name})", tf_check.binding)
+          if @excluded.member?(meth.to_s)
+            # Turn off tracing for any calls from this frame.  Note
+            # that Ruby turns of tracing in the thread of a hook while
+            # it is running, but I don't think this is as good as
+            # turning it off in the frame and frames called from that.
+            # Example: if a trace hook yields to or calls a block
+            # outside not derived from the frame, then tracing should
+            # start again.  But either way, since RubyVM::ThreadFrame
+            # allows control over tracing *any* decision is not
+            # irrevocable, just possibly unhelpful.
+            tf_check.trace_off = true
+            return 
+          end
+        end
+      rescue NameError
+      rescue SyntaxError
+      rescue ArgumentError
+      end
+      while %w(IFUNC).member?(tf.type) do 
+        tf = tf.prev 
+      end
+
+      # There is what looks like a a bug in Ruby where self.class for C
+      # functions are not set correctly. Until this is fixed in what I
+      # consider a more proper way, we'll hack around this by passing
+      # the binding as the optional arg parameter.
+      arg = 
+        if 'CFUNC' == tf.type && NilClass != klass 
+          klass 
+        elsif 'raise' == event
+          # As a horrible hack to be able to get the raise message on a
+          # 'raise' event before the event occurs, I changed RubyVM to store
+          # the message in the class field.
+          klass
+        else
+          nil
+        end
+
+      retval = @hook_proc.call(event, tf, arg)
+      if retval.respond_to?(:ancestors) && retval.ancestors.include?(Exception)
+        raise retval 
+      end
+    end
+
+    # Replacement for Kernel.add_trace_func. hook_proc should be a Proc that
+    # takes two arguments, a string event, and threadframe object.
+    def add_trace_func(hook_proc, event_mask=nil)
+      if hook_proc.nil?
+        Kernel.set_trace_func(nil)
+        return
+      end
+      raise TypeError, 
+      "trace_func needs to be Proc or nil (is #{hook_proc.class})" unless 
+        hook_proc.is_a?(Proc)
+      raise TypeError, "arity of hook_proc should be 2 or -3 (is #{hook_proc.arity})" unless 
+        2 == hook_proc.arity || -3 == hook_proc.arity
+      @hook_proc = hook_proc
+      if event_mask
+        Trace::add_trace_func(method(:trace_hook).to_proc, event_mask)
+      else
+        Kernel.add_trace_func(method(:trace_hook).to_proc)
+      end
+    end
+
+    # FIXME: remove just this trace function
+    def remove_trace_func
+        Kernel.clear_trace_func
+    end
+
+
+    # Replacement for Kernel.set_trace_func. proc should be a Proc that
+    # takes two arguments, a string event, and threadframe object.
+    def set_trace_func(hook_proc, event_mask=nil)
+      if hook_proc.nil?
+        Kernel.set_trace_func(nil)
+        return
+      end
+      raise TypeError, 
+      "trace_func needs to be Proc or nil (is #{hook_proc.class})" unless 
+        hook_proc.is_a?(Proc)
+      raise TypeError, "arity of hook_proc should be 2 or -3 (is #{hook_proc.arity})" unless 
+        2 == hook_proc.arity || -3 == hook_proc.arity
+      @hook_proc = hook_proc
+      if event_mask
+        Trace::set_trace_func(method(:trace_hook).to_proc, event_mask)
+      else
+        Kernel.set_trace_func(method(:trace_hook).to_proc)
+      end
+    end
+  end
+end
+
+if __FILE__ == $0
+  include Trace
+
+  def square(x) # :nodoc:
+    y = x * x
+    puts "the square of #{x} is #{y}\n"
+    y
+  end
+
+  def my_hook(event, tf, arg=nil) # :nodoc:
+    puts "#{event} #{tf.source_container[1]} #{tf.source_location[0]}"
+    @events << event
+    @line_nos << ((tf.source_location) ? tf.source_location[0] : '?')
+  end
+
+  def trace_test(dont_trace_me) # :nodoc:
+    @start_line = __LINE__
+    @trace_filter << self.method(:trace_test) if dont_trace_me
+    p @trace_filter.member?(self.method(:trace_test))
+
+    # Start tracing.
+    event_mask = DEFAULT_EVENT_MASK # & ~(C_RETURN_EVENT_MASK | RETURN_EVENT_MASK)
+    @trace_filter.set_trace_func(method(:my_hook).to_proc, event_mask)
+    square(10)
+    x = 100
+    square(x)
+    @end_line = __LINE__
+  end
+
+  def setup # :nodoc:
+    @events   = []
+    @line_nos = []
+    @trace_filter.clear
+  end
+
+  def print_trace # :nodoc:
+    @line_nos.each_with_index do |line_no, i|
+      print "%2d %s %s\n" % [i, @events[i], line_no]
+    end
+  end
+
+  @trace_filter = Trace::Filter.new
+  markers       = '*' * 10
+
+  [[false, 'out'], [true, '']].each do |arg, suffix|
+    setup 
+    puts "%s with%s ignore %s" % [markers, suffix, markers]
+    trace_test(arg)
+    @trace_filter.set_trace_func(nil)
+    print_trace
+  end
+
+  @line_nos.each_with_index do 
+    |line_no, i|
+    if (@start_line..@end_line).member?(line_no)
+      puts "We should not have found a line number in #{@start_line}..#{@end_line}." 
+      puts "Got line number #{line_no} at index #{i}, event #{@events[i]}"
+    end
+  end
+end

data/test/unit/test-event2bitmask.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+require 'test/unit'
+require 'set'
+require_relative '../../lib/trace_mod'
+
+class TestEvent2Bitmask < Test::Unit::TestCase
+  include Trace
+  
+  def test_basic
+    test_pair = events2bitmask([LINE_EVENT_MASK, CLASS_EVENT_MASK])
+    test_mask, unhandled = test_pair
+    assert_equal(test_pair, 
+                 events2bitmask(Set.new([LINE_EVENT_MASK, CLASS_EVENT_MASK])))
+    assert_equal([:class, :line], bitmask2events(test_mask))
+
+    EVENT2MASK.each do |mask_name, bit_value|
+      assert_equal([mask_name], bitmask2events(bit_value))
+    end
+
+    assert_equal(test_pair, events2bitmask(['LINE', 'Class']))
+    assert_equal(test_pair, events2bitmask(Set.new(['LINE', 'Class'])))
+    [[:foo, 'bar'], ['C call', ['bar']]].each do |bad|
+      assert_equal([0, bad], events2bitmask(bad))
+    end
+  end
+end

data/test/unit/test-trace-hook.rb

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+require 'test/unit'
+require_relative '../../ext/trace'
+
+# Testing RubyVM::TraceHook
+class TestTraceHook < Test::Unit::TestCase
+
+  def setup
+    set_trace_func(nil)
+  end
+
+  def test_trace_hooks
+    tt = RubyVM::TraceHook::trace_hooks
+    assert_equal([], tt)
+
+    set_trace_func(Proc.new { 1  })
+    tt = RubyVM::TraceHook::trace_hooks
+
+    assert_equal(1, tt.size)
+    assert tt[0].event_mask.is_a?(Fixnum)
+    
+    set_trace_func(Proc.new { }, 5)
+    tt = RubyVM::TraceHook::trace_hooks
+
+    assert_equal(1, tt.size)
+
+    set_trace_func(nil)
+    tt = RubyVM::TraceHook::trace_hooks
+    assert_equal([], tt)
+    
+  end
+
+  # Test getting and setting event mask of a trace hook
+  def test_event
+    set_trace_func(Proc.new { }, 5)
+    tt = RubyVM::TraceHook::trace_hooks
+    assert_equal(5, tt[0].event_mask)
+
+    tt[0].event_mask = 6;
+    assert_equal(6, tt[0].event_mask)
+
+    set_trace_func(nil)
+    assert_raises RubyVM::TraceHookError do 
+      tt[0].event_mask 
+    end
+
+    assert_raises RubyVM::TraceHookError do 
+      tt[0].event_mask = 10
+    end
+
+  end
+
+  # Test getting and setting proc of a trace hook
+  def test_proc
+    p = Proc.new { 1 }
+    set_trace_func(p)
+    tt = RubyVM::TraceHook::trace_hooks
+    assert_equal(p, tt[0].proc)
+    assert_equal 1, tt[0].proc.call
+
+    p2 = Proc.new { 2 }
+    assert_raises TypeError do
+      tt[0].proc = 5
+    end
+    tt[0].proc = p2
+
+    assert_equal(p2, tt[0].proc)
+    assert_equal 2, tt[0].proc.call
+
+    set_trace_func(nil)
+    assert_raises RubyVM::TraceHookError do 
+      tt[0].proc
+    end
+
+    assert_raises TypeError do 
+      tt[0].proc = 6
+    end
+
+    # Test valid?
+    def test_valid
+      tt = RubyVM::TraceHook::trace_hooks
+      assert_equal(true, tt[0].valid?)
+      set_trace_func(Proc.new {} )
+      tt = RubyVM::TraceHook::trace_hooks
+      assert_equal(true, tt[0].valid?)
+      set_trace_func(Proc.new { 1 } )
+      assert_equal(false, tt[0].valid?)
+      tt = RubyVM::TraceHook::trace_hooks
+      assert_equal(true, tt[0].valid?)
+      set_trace_func(nil)
+      GC.start
+      assert_equal(false, tt[0].valid?)
+    end
+  end
+end

data/test/unit/test-trace_mod.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+require 'test/unit'
+require_relative '../../lib/trace_mod'
+
+# Testing Trace Module
+class TestTrace < Test::Unit::TestCase
+
+  def test_set_trace_func
+    @events = []
+    def foo ; end
+
+    event_set = [:call, :return]
+    Trace::set_trace_func(Proc.new {|e, tf| @events << e}, event_set)
+    foo
+    call_return_mask = Trace::event_masks[0]
+    assert_equal(Fixnum, call_return_mask.class)
+
+    Trace::event_masks = [:call]
+    foo
+    call_mask = Trace::event_masks[0]
+    Trace::set_trace_func(nil)
+
+    @events.each do |e| 
+      assert_equal(true, event_set.member?(e.to_sym), 
+                   "#{e} should be in #{event_set}")
+    end
+    
+    assert_equal(true,
+                 ((call_return_mask > call_mask) &&
+                  (0 != (call_return_mask & call_mask))))
+                 
+    @events = []
+    Trace::set_trace_func(nil)
+    @events.each do |e| 
+      assert_equal(true, event_set.member?(e.to_sym), 
+                   "#{e} should be in #{event_set}")
+    end
+
+    assert_equal(nil, Trace::event_masks[0])
+  end
+
+end

data/test/unit/test-tracefilter.rb

@@ -0,0 +1,115 @@
+#!/usr/bin/env ruby
+require 'test/unit'
+require_relative '../../lib/tracefilter'
+
+# Testing Trace Filter class
+class TestTraceFilter < Test::Unit::TestCase
+
+  def setup
+    $args     = []
+    $events   = []
+    $line_nos = []
+    @trace_filter = Trace::Filter.new unless defined?(@trace_filter)
+    @trace_filter.clear
+  end
+
+  def teardown
+    $args   = []
+    $events = []
+    $line_nos = []
+  end
+
+  # Just something to trace
+  def square(x)
+    x * x
+  end
+
+  # Save stuff from the trace for inspection later.
+  def my_hook(event, tf, arg=nil)
+    $args     << arg if arg
+    $events   << event
+    $line_nos << tf.source_location[0] if tf.source_location
+  end
+
+  def trace_test(dont_trace_me)
+    $start_line = __LINE__
+    me = self.method(:trace_test)
+    assert_equal(false, @trace_filter.member?(me))
+    @trace_filter << self.method(:trace_test) if dont_trace_me
+    assert_equal(dont_trace_me, @trace_filter.member?(me))
+
+    # Start tracing.
+    @trace_filter.set_trace_func(method(:my_hook).to_proc)
+    square(10)
+    x = 100
+    square(x)
+    $end_line = __LINE__
+  end
+
+  def print_trace
+    $line_nos.each_with_index do |line_no, i|
+      print "%2d %s %s\n" % [i, $events[i], line_no]
+    end
+    p $args
+  end
+
+  def test_basic
+    trace_test(true)
+    @trace_filter.set_trace_func(nil)
+    print_trace if $DEBUG
+
+    assert_equal(false, $events.empty?, 
+                 'We should have gotting some trace output')
+    assert_equal([Kernel], $args,
+                 'C call/returns set $args')
+
+    $line_nos.each_with_index do 
+      |line_no, i|
+      assert_equal(false, ($start_line..$end_line).member?(line_no),
+                   "We should not find a line number in " +
+                   "#{$start_line}..#{$end_line}; " + 
+                   "got line number #{line_no} at index #{i}, " + 
+                   "event #{$events[i]}")
+    end
+    untraced_line_nos = $line_nos
+    untrace_events = $events
+
+    setup
+    trace_test(false)
+    @trace_filter.set_trace_func(nil)
+    print_trace if $DEBUG
+
+    assert_equal(true, $line_nos.size > untraced_line_nos.size,
+                 'We should have traced more stuff than untraced output')
+
+    found_one = false
+    $line_nos.each_with_index do 
+      |line_no, i|
+      if ($start_line..$end_line).member?(line_no)
+        found_one = true
+        break
+      end
+    end
+    assert_equal(true, found_one, 
+                 'We should have found a line number for at least one event ' +
+                 'in traced output.')
+
+    assert_raises TypeError do 
+      @trace_filter.set_trace_func(method(:trace_test))
+    end
+  end
+
+  # Save stuff from the trace for inspection later.
+  def raise_hook(event, tf, arg=nil)
+    return unless 'raise' == event
+    $args     << arg.to_s
+  end
+
+  def test_raise_sets_errmsg
+    @trace_filter.set_trace_func(method(:raise_hook).to_proc)
+    1/0 rescue nil
+    @trace_filter.set_trace_func(nil)
+    assert_equal(['divided by 0'], $args)
+  end
+
+end