class TracePoint

TracePoint

A TracePoint is a Binding with the addition event information. And it's a better way to use set_trace_func.

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

CodePoint alias for Binding has been deprecated.

We can't subclass Binding, so we delegate.

Constants

EVENT_MAP

methods for working with events

VERSION

TODO: this is here only b/c of lookup bugs in Ruby 1.8.x.

Attributes

back_binding[RW]

– instance ——————-

binding[RW]

– instance ——————-

event[RW]

– instance ——————-

file[RW]

– instance ——————-

line[RW]

– instance ——————-

Public Class Methods

activate() click to toggle source

Activate tracing.

# File lib/tracepoint.rb, line 71
def activate
  @@active = true
  bb_stack = []
  fn = lambda do |e, f, l, m, b, k|
    unless k == TracePoint or (k == Kernel && m == :set_trace_func)
      #(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, f, l, m, b, bb)
      @@procs.each{ |fn| fn.call(tp) }
    end
  end
  set_trace_func(fn)
end
active?() click to toggle source

Is tracing active?

# File lib/tracepoint.rb, line 66
def active?
  @@active
end
clear(name=nil) click to toggle source

Clear all trace procedures, or a specific trace by name.

# File lib/tracepoint.rb, line 97
def clear(name=nil)
  if name
    raise "Undefined trace -- #{name}" unless @@index.key?(name)
    @@procs.delete(@@index.delete(name))
  else
    deactivate
    @@index = {}
    @@procs = []
  end
end
const_missing(name) click to toggle source

Access metadata as constants.

Calls superclass method
# File lib/tracepoint.rb, line 42
def self.const_missing(name)
  name = name.to_s.downcase
  metadata[name] || super(name)
end
deactivate() click to toggle source

Deactivate tracing.

# File lib/tracepoint.rb, line 91
def deactivate
  @@active = false
  set_trace_func nil
end
metadata() click to toggle source

Access to metadata.

# File lib/tracepoint.rb, line 34
def self.metadata
  @metadata ||= (
    require 'yaml'
    YAML.load(File.new(File.dirname(__FILE__) + '/tracepoint.yml'))
  )
end
new( event, file, line, method, bind, back_binding=bind ) click to toggle source

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/tracepoint.rb, line 116
def initialize( event, file, line, method, bind, back_binding=bind )
  @event   = event
  @file    = file
  @line    = line
  @method  = method
  @binding = bind || TOPLEVEL_BINDING #?
  @back_binding = back_binding
end
trace(name=nil, &procedure) click to toggle source

Trace execution using a TracePoint.

# File lib/tracepoint.rb, line 60
def trace(name=nil, &procedure)
  @@index[name] = procedure if name
  @@procs << procedure
end

Public Instance Methods

===(e) click to toggle source

For use in case conditions

# File lib/tracepoint.rb, line 178
def ===(e)
  EVENT_MAP[e].include?(@event)
end
back() click to toggle source

Shorthand for back_binding.

# File lib/tracepoint.rb, line 131
def back
  @back_binding
end
bind() click to toggle source

Shorthand for binding.

# File lib/tracepoint.rb, line 126
def bind
  @binding
end
callee() click to toggle source

Returns the name of the event's method.

# File lib/tracepoint.rb, line 146
def callee ; @method ; end
Also aliased as: method_name
event?() click to toggle source

Is the trace point defined or undefined?

# File lib/tracepoint.rb, line 174
def event? ; !! @event ; end
event_map(e) click to toggle source
# File lib/tracepoint.rb, line 171
def event_map(e) ; EVENT_MAP[e] ; end
eventless?() click to toggle source
# File lib/tracepoint.rb, line 175
def eventless? ; ! @event ; end
method_name()

def method ; @method ; end # TODO Conflict with Kernel#method ?

Alias for: callee
self() click to toggle source

Delegates “self” to the binding which in turn delegates the binding object.

# File lib/tracepoint.rb, line 137
def self
  @binding.self #if @binding
end