TracePoint

A TracePoint is a Binding with the addition of event information. Among other things, it functions very well as the join-point for Event-based AOP.

Usage

  TracePoint.trace { |tp|
    puts "#{tp.self.class}\t#{tp.called}\t#{tp.event}\t#{tp.return?}\t#{tp.back == tp.bind}"
  }

  1 + 1

produces

  Class   trace   return     true    false
  Object          line       false   false
  Fixnum  +       c-call     false   false
  Fixnum  +       c-return   false   false

Notes

You can‘t subclass Binding, so we delegate (which is better anyway).

Methods
=== active active= back bind called callee event? event_map eventless? method_name new self trace
Constants
EVENT_MAP = { :all => ['call', 'c-call', 'return', 'c-return', 'line', 'class', 'end', 'raise'], :before => ['call', 'c-call'], :after => ['return', 'c-return'], :call => ['call'], :return => ['return'], :ccall => ['c-call'], :creturn => ['c-return'], :line => ['line'], :class => ['class'], :end => ['end'], :raise => ['raise']
  methods for working with events
Attributes
[RW] back_binding — instance ——————-
[RW] binding — instance ——————-
[RW] event — instance ——————-
Public Class methods
active()
# File lib/more/facets/tracepoint.rb, line 86
    def active ; @@active ; end
active=(x)
# File lib/more/facets/tracepoint.rb, line 88
    def active=(x)
      @@active = x ? true : false
      unless @@active
        set_trace_func nil
      end
    end
new( event, method, bind, back_binding=bind )

Until Ruby has a built-in way to get the name of the calling method that information must be passed into the TracePoint.

# File lib/more/facets/tracepoint.rb, line 121
  def initialize( event, method, bind, back_binding=bind )
    @event = event
    @method = method
    @binding = bind
    @back_binding = back_binding
  end
trace( {|| ...}

Trace execution using a TracePoint.

# File lib/more/facets/tracepoint.rb, line 96
    def trace # :yield:
      if active
        bb_stack = []
        set_trace_func proc{ |e, f, l, m, b, k|
          #(p e, f, l, m, b, k, @@bb_stack; puts "---") if $DEBUG
          if ['call','c-call','class'].include?(e)
            bb_stack << b
          elsif ['return','c-return','end'].include?(e)
            bb = bb_stack.pop
          end
          b = bb if ! b    # this sucks!
          tp = TracePoint.new(e,m,b,bb)
          yield(tp)
        }
      end
    end
Public Instance methods
===(e)

For use in case conditions

# File lib/more/facets/tracepoint.rb, line 173
  def ===(e)
    EVENT_MAP[e].include?(@event)
  end
back()

shorthand for back_binding

# File lib/more/facets/tracepoint.rb, line 132
  def back ; @back_binding ; end
bind()

shorthand for binding

# File lib/more/facets/tracepoint.rb, line 129
  def bind ; @binding ; end
called()

Alias for callee

This method is also aliased as method_name
callee()

Returns the name of the event‘s method. This could delegate to the binding if Ruby had an internal way to retrieve the current method name.

This method is also aliased as called
# File lib/more/facets/tracepoint.rb, line 141
  def callee ; @method ; end
event?()

Is the trace point defined or undefined?

# File lib/more/facets/tracepoint.rb, line 169
  def event? ; !! @event ; end
event_map(e)
# File lib/more/facets/tracepoint.rb, line 166
  def event_map(e) ; EVENT_MAP[e] ; end
eventless?()
# File lib/more/facets/tracepoint.rb, line 170
  def eventless? ; ! @event ; end
method_name()

Alias for called

self()

Delegates "self" to the binding which in turn delegates the binding object.

# File lib/more/facets/tracepoint.rb, line 136
  def self ; @binding.self ; end