Class: TracePoint

Relationships & Source Files
Inherits:	Object
Defined in:	trace_point.rb, vm_trace.c

Overview

A class that provides the functionality of Kernel.set_trace_func in a well-structured Object-Oriented API.

Example

Use TracePoint to gather information specifically for exceptions:

trace = TracePoint.new(:raise) do |tp|
  p [tp.lineno, tp.event, tp.raised_exception]
end
#=> #<TracePoint:disabled>

trace.enable  #=> false

0 / 0
#=> [5, :raise, #<ZeroDivisionError: divided by 0>]

Events

If you don’t specify the types of events you want to listen for, TracePoint will include all available events.

Note: Do not depend on the current event set, as this list is subject to change. Instead, it is recommended to specify the types of events you want to use.

To filter what is traced, you can pass any of the following as events:

:line: Execute an expression or statement on a new line.
:class: Start a class or module definition.
:end: Finish a class or module definition.
:call: Call a Ruby method.
:return: Return from a Ruby method.
:c_call: Call a C-language routine.
:c_return: Return from a C-language routine.
:raise: Raise an exception.
:rescue: Rescue an exception.
:b_call: Event hook at block entry.
:b_return: Event hook at block ending.
:a_call: Event hook at all calls (call, b_call, and c_call).
:a_return: Event hook at all returns (return, b_return, and c_return).
:thread_begin: Event hook at thread beginning.
:thread_end: Event hook at thread ending.
:fiber_switch: Event hook at fiber switch.
:script_compiled: New Ruby code compiled (with eval, load, or require).

Class Method Summary

.allow_reentry

Generally, while a TracePoint callback is running, other registered callbacks are not called to avoid confusion from reentrance.
.new(*events) {|tp| ... } ⇒ tp constructor

Returns a new TracePoint object, not enabled by default.
.stat ⇒ Object

Returns internal information of TracePoint.
.trace(*events) {|tp| ... } ⇒ Object

A convenience method for .new that activates the trace automatically.

Instance Attribute Summary

#enabled? ⇒ Boolean readonly

Returns the current status of the trace.

Instance Method Summary

#binding

Returns the generated binding object from the event.
#callee_id

Returns the called name of the method being called.
#defined_class

Returns the class or module of the method being called.
#disable ⇒ Boolean

Deactivates the trace.
#enable(target: nil, target_line: nil, target_thread: nil) ⇒ Boolean

Activates the trace.
#eval_script

Returns the compiled source code (String) from eval methods on the :script_compiled event.
#event

Returns the type of event.
#inspect ⇒ String

Returns a string containing a human-readable TracePoint status.
#instruction_sequence

Returns the compiled instruction sequence represented by a ::RubyVM::InstructionSequence instance on the :script_compiled event.
#lineno

Returns the line number of the event.
#method_id

Returns the name at the definition of the method being called.
#parameters

Returns the parameter definitions of the method or block that the current hook belongs to.
#path

Returns the path of the file being executed.
#raised_exception

Returns the exception raised on the :raise event or rescued on the :rescue event.
#return_value

Returns the return value from :return, :c_return, and :b_return events.
#self

Returns the trace object during the event.

Constructor Details

.new(*events) {|tp| ... } ⇒ `tp`

Returns a new TracePoint object, not enabled by default.

To activate the TracePoint object, use #enable:

trace = TracePoint.new(:call) do |tp|
  p [tp.lineno, tp.defined_class, tp.method_id, tp.event]
end
#=> #<TracePoint:disabled>

trace.enable  #=> false

puts "Hello, TracePoint!"
# ...
# [48, IRB::Notifier::AbstractNotifier, :printf, :call]
# ...

To deactivate the trace, use #disable.

trace.disable

See TracePoint@Events for possible events and more information.

A block must be given; otherwise, an ::ArgumentError is raised.

If the trace method isn’t included in the given events filter, a ::RuntimeError is raised.

TracePoint.trace(:line) do |tp|
  p tp.raised_exception
end
#=> RuntimeError: 'raised_exception' not supported by this event

If the trace method is called outside a block, a ::RuntimeError is raised.

TracePoint.trace(:line) do |tp|
  $tp = tp
end
$tp.lineno #=> access from outside (RuntimeError)

Access from other threads is also forbidden.

[ GitHub ]

# File 'trace_point.rb', line 94


def self.new(*events)
  Primitive.attr! :use_block
  Primitive.tracepoint_new_s(events)
end

Class Method Details

.allow_reentry

Generally, while a TracePoint callback is running, other registered callbacks are not called to avoid confusion from reentrance. This method allows reentrance within a given block. Use this method carefully to avoid infinite callback invocation.

If called when reentrance is already allowed, it raises a ::RuntimeError.

Example:

# Without reentry
# ---------------

line_handler = TracePoint.new(:line) do |tp|
  next if tp.path != __FILE__ # Only works in this file
  puts "Line handler"
  binding.eval("class C; end")
end.enable

class_handler = TracePoint.new(:class) do |tp|
  puts "Class handler"
end.enable

class B
end

# This script will print "Class handler" only once: when inside the :line
# handler, all other handlers are ignored.

# With reentry
# ------------

line_handler = TracePoint.new(:line) do |tp|
  next if tp.path != __FILE__ # Only works in this file
  next if (__LINE__..__LINE__+3).cover?(tp.lineno) # Prevent infinite calls
  puts "Line handler"
  TracePoint.allow_reentry { binding.eval("class C; end") }
end.enable

class_handler = TracePoint.new(:class) do |tp|
  puts "Class handler"
end.enable

class B
end

# This will print "Class handler" twice: inside the allow_reentry block in the :line
# handler, other handlers are enabled.

Note that the example shows the principal effect of the method, but its practical usage is for debugging libraries that sometimes require other libraries’ hooks to not be affected by the debugger being inside trace point handling. Precautions should be taken against infinite recursion in this case (note that we needed to filter out calls by itself from the :line handler, otherwise it would call itself infinitely).

[ GitHub ]

# File 'trace_point.rb', line 198


def self.allow_reentry
  Primitive.attr! :use_block
  Primitive.tracepoint_allow_reentry
end

.stat ⇒ Object

Returns internal information of TracePoint.

The contents of the returned value are implementation-specific and may change in the future.

This method is only for debugging TracePoint itself.

[ GitHub ]

# File 'trace_point.rb', line 117


def self.stat
  Primitive.tracepoint_stat_s
end

.trace(*events) {|tp| ... } ⇒ Object

A convenience method for .new that activates the trace automatically.

trace = TracePoint.trace(:call) { |tp| [tp.lineno, tp.event] }
#=> #<TracePoint:enabled>

trace.enabled?  #=> true

[ GitHub ]

# File 'trace_point.rb', line 132


def self.trace(*events)
  Primitive.attr! :use_block
  Primitive.tracepoint_trace_s(events)
end

Instance Attribute Details

#enabled? ⇒ `Boolean` (readonly)

Returns the current status of the trace.

[ GitHub ]

# File 'trace_point.rb', line 304


def enabled?
  Primitive.tracepoint_enabled_p
end

Instance Method Details

#binding

Returns the generated binding object from the event.

Note that for :c_call and :c_return events, the method returns nil, since C methods themselves do not have bindings.

[ GitHub ]

# File 'trace_point.rb', line 381


def binding
  Primitive.tracepoint_attr_binding
end

#callee_id

Returns the called name of the method being called.

[ GitHub ]

# File 'trace_point.rb', line 337


def callee_id
  Primitive.tracepoint_attr_callee_id
end

#defined_class

Returns the class or module of the method being called.

class C; def foo; end; end
trace = TracePoint.new(:call) do |tp|
  p tp.defined_class #=> C
end.enable do
  C.new.foo
end

If the method is defined by a module, then that module is returned.

module M; def foo; end; end
class C; include M; end
trace = TracePoint.new(:call) do |tp|
  p tp.defined_class #=> M
end.enable do
  C.new.foo
end

Note: #defined_class returns the singleton class.

The 6th block parameter of Kernel.set_trace_func passes the original class attached by the singleton class.

This is a difference between Kernel.set_trace_func and TracePoint.

class C; def self.foo; end; end
trace = TracePoint.new(:call) do |tp|
  p tp.defined_class #=> #<Class:C>
end.enable do
  C.foo
end

[ GitHub ]

# File 'trace_point.rb', line 373


def defined_class
  Primitive.tracepoint_attr_defined_class
end

#disable ⇒ `Boolean` #disable ⇒ Object

Deactivates the trace.

Returns true if the trace was enabled. Returns false if the trace was disabled.

trace.enabled?  #=> true
trace.disable   #=> true (previous status)
trace.enabled?  #=> false
trace.disable   #=> false

If a block is given, the trace will only be disabled within the scope of the block.

trace.enabled?  #=> true

trace.disable do
  trace.enabled?
  # Only disabled for this block
end

trace.enabled?  #=> true

Note: You cannot access event hooks within the block.

trace.disable { p tp.lineno }
#=> RuntimeError: access from outside

[ GitHub ]

# File 'trace_point.rb', line 295


def disable
  Primitive.attr! :use_block
  Primitive.tracepoint_disable_m
end

#enable(target: nil, target_line: nil, target_thread: nil) ⇒ `Boolean` #enable(target: nil, target_line: nil, target_thread: :default) ⇒ Object

Activates the trace.

Returns true if the trace was enabled. Returns false if the trace was disabled.

trace.enabled?  #=> false
trace.enable    #=> false (previous state)
                #   trace is enabled
trace.enabled?  #=> true
trace.enable    #=> true (previous state)
                #   trace is still enabled

If a block is given, the trace will only be enabled during the block execution. If target and target_line are both nil, then target_thread will default to the current thread if a block is given.

trace.enabled?  #=> false

trace.enable do
  trace.enabled?
  # Only enabled for this block and thread
end

trace.enabled?  #=> false

The target, target_line, and target_thread parameters are used to limit tracing to specified code objects. target should be a code object for which RubyVM::InstructionSequence.of will return an instruction sequence.

t = TracePoint.new(:line) { |tp| p tp }

def m1
  p 1
end

def m2
  p 2
end

t.enable(target: method(:m1))

m1
# Prints #<TracePoint:line test.rb:4 in `m1'>
m2
# Prints nothing

Note: You cannot access event hooks within the enable block.

trace.enable { p tp.lineno }
#=> RuntimeError: access from outside

[ GitHub ]

# File 'trace_point.rb', line 259


def enable(target: nil, target_line: nil, target_thread: :default)
  Primitive.attr! :use_block
  Primitive.tracepoint_enable_m(target, target_line, target_thread)
end

#eval_script

Returns the compiled source code (String) from eval methods on the :script_compiled event. If loaded from a file, it returns nil.

[ GitHub ]

# File 'trace_point.rb', line 407


def eval_script
  Primitive.tracepoint_attr_eval_script
end

#event

Returns the type of event.

See TracePoint@Events for more information.

[ GitHub ]

# File 'trace_point.rb', line 311


def event
  Primitive.tracepoint_attr_event
end

#inspect ⇒ String

Returns a string containing a human-readable TracePoint status.

[ GitHub ]

# File 'trace_point.rb', line 104


def inspect
  Primitive.tracepoint_inspect
end

#instruction_sequence

Returns the compiled instruction sequence represented by a ::RubyVM::InstructionSequence instance on the :script_compiled event.

Note that this method is CRuby-specific.

[ GitHub ]

# File 'trace_point.rb', line 415


def instruction_sequence
  Primitive.tracepoint_attr_instruction_sequence
end

#lineno

Returns the line number of the event.

[ GitHub ]

# File 'trace_point.rb', line 316


def lineno
  Primitive.tracepoint_attr_lineno
end

#method_id

Returns the name at the definition of the method being called.

[ GitHub ]

# File 'trace_point.rb', line 332


def method_id
  Primitive.tracepoint_attr_method_id
end

#parameters

Returns the parameter definitions of the method or block that the current hook belongs to. The format is the same as for Method#parameters.

[ GitHub ]

# File 'trace_point.rb', line 327


def parameters
  Primitive.tracepoint_attr_parameters
end

#path

Returns the path of the file being executed.

[ GitHub ]

# File 'trace_point.rb', line 321


def path
  Primitive.tracepoint_attr_path
end

#raised_exception

Returns the exception raised on the :raise event or rescued on the :rescue event.

[ GitHub ]

# File 'trace_point.rb', line 401


def raised_exception
  Primitive.tracepoint_attr_raised_exception
end

#return_value

Returns the return value from :return, :c_return, and :b_return events.

[ GitHub ]

# File 'trace_point.rb', line 396


def return_value
  Primitive.tracepoint_attr_return_value
end

#self

Returns the trace object during the event.

Similar to the following, but it returns the correct object (the method receiver) for :c_call and :c_return events:

trace.binding.eval('self')

[ GitHub ]

# File 'trace_point.rb', line 391


def self
  Primitive.tracepoint_attr_self
end

Class: TracePoint

Overview

Example

Events

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(*events) {|tp| ... } ⇒ tp

Class Method Details

.allow_reentry

.stat ⇒ Object

.trace(*events) {|tp| ... } ⇒ Object

Instance Attribute Details

#enabled? ⇒ Boolean (readonly)

Instance Method Details

#binding

#callee_id

#defined_class

#disable ⇒ Boolean #disable ⇒ Object

#enable(target: nil, target_line: nil, target_thread: nil) ⇒ Boolean #enable(target: nil, target_line: nil, target_thread: :default) ⇒ Object

#eval_script

#event

#inspect ⇒ String

#instruction_sequence

#lineno

#method_id

#parameters

#path

#raised_exception

#return_value

#self

.new(*events) {|tp| ... } ⇒ `tp`

#enabled? ⇒ `Boolean` (readonly)

#disable ⇒ `Boolean` #disable ⇒ Object

#enable(target: nil, target_line: nil, target_thread: nil) ⇒ `Boolean` #enable(target: nil, target_line: nil, target_thread: :default) ⇒ Object