Class: TracePoint

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

Overview

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

Example

We can 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 type of events you want to listen for, TracePoint will include all available events.

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

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

:line: execute code 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
:b_call: event hook at block entry
:b_return: event hook at block ending
:thread_begin: event hook at thread beginning
:thread_end: event hook at thread ending
:fiber_switch: event hook at fiber switch

Class Method Summary

.new(*events) {|obj| ... } ⇒ Object constructor

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

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

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

Instance Attribute Summary

#enabled? ⇒ Boolean readonly

The current status of the trace.

Instance Method Summary

#enable ⇒ Boolean

Activates the trace.
#binding

Return the generated binding object from event.
#callee_id

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

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

Deactivates the trace.
#enable(target: nil, target_line: nil, &blk)
#eval_script

Compiled source code (String) on *eval methods on the :script_compiled event.
#event

Type of event.
#inspect ⇒ String

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

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

Line number of the event.
#method_id

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

Return the parameters of the method or block that the current hook belongs to.
#path

Path of the file being run.
#raised_exception

Value from exception raised on the :raise event.
#return_value

Return value from :return, c_return, and b_return event.
#self

Return the trace object during event.

Constructor Details

.new(*events) {|obj| ... } ⇒ Object

Returns a new TracePoint object, not enabled by default.

Next, in order to activate the trace, you must 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]
# ...

When you want to deactivate the trace, you must 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 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 'vm_trace.c', line 1600


static VALUE
tracepoint_new_s(int argc, VALUE *argv, VALUE self)
{
    rb_event_flag_t events = 0;
    int i;

    if (argc > 0) {
	for (i=0; i<argc; i++) {
	    events |= symbol2event_flag(argv[i]);
	}
    }
    else {
	events = RUBY_EVENT_TRACEPOINT_ALL;
    }

    if (!rb_block_given_p()) {
	rb_raise(rb_eArgError, "must be called with a block");
    }

    return tracepoint_new(self, 0, events, 0, 0, rb_block_proc());
}

Class Method Details

.stat ⇒ Object

Returns internal information of TracePoint.

The contents of the returned value are implementation specific. It may be changed in future.

This method is only for debugging TracePoint itself.

[ GitHub ]

# File 'vm_trace.c', line 1714


static VALUE
tracepoint_stat_s(VALUE self)
{
    rb_vm_t *vm = GET_VM();
    VALUE stat = rb_hash_new();

    tracepoint_stat_event_hooks(stat, vm->self, vm->global_hooks.hooks);
    /* TODO: thread local hooks */

    return stat;
}

.trace(*events) {|obj| ... } ⇒ 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 'vm_trace.c', line 1622


static VALUE
tracepoint_trace_s(int argc, VALUE *argv, VALUE self)
{
    VALUE trace = tracepoint_new_s(argc, argv, self);
    rb_tracepoint_enable(trace);
    return trace;
}

Instance Attribute Details

#enabled? ⇒ `Boolean` (readonly)

The current status of the trace

[ GitHub ]

# File 'vm_trace.c', line 1486


VALUE
rb_tracepoint_enabled_p(VALUE tpval)
{
    rb_tp_t *tp = tpptr(tpval);
    return tp->tracing ? Qtrue : Qfalse;
}

Instance Method Details

#enable ⇒ `Boolean` #enable ⇒ Object

Activates the trace

Return true if trace was enabled. Return false if 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 within the scope of the block.

trace.enabled?
#=> false

trace.enable do
    trace.enabled?
    # only enabled for this block
end

trace.enabled?
#=> false

Note: You cannot access event hooks within the block.

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

[ GitHub ]

# File 'vm_trace.c', line 1397


static VALUE
tracepoint_enable_m(VALUE tpval, VALUE target, VALUE target_line)
{
    rb_tp_t *tp = tpptr(tpval);
    int previous_tracing = tp->tracing;

    if (NIL_P(target)) {
        if (!NIL_P(target_line)) {
            rb_raise(rb_eArgError, "only target_line is specified");
        }
        rb_tracepoint_enable(tpval);
    }
    else {
        rb_tracepoint_enable_for_target(tpval, target, target_line);
    }

    if (rb_block_given_p()) {
	return rb_ensure(rb_yield, Qundef,
			 previous_tracing ? rb_tracepoint_enable : rb_tracepoint_disable,
			 tpval);
    }
    else {
	return previous_tracing ? Qtrue : Qfalse;
    }
}

#binding

Return the generated binding object from event

[ GitHub ]

# File 'vm_trace.c', line 1127


static VALUE
tracepoint_attr_binding(VALUE tpval)
{
    return rb_tracearg_binding(get_trace_arg());
}

#callee_id

Return the called name of the method being called

[ GitHub ]

# File 'vm_trace.c', line 1078


static VALUE
tracepoint_attr_callee_id(VALUE tpval)
{
    return rb_tracearg_callee_id(get_trace_arg());
}

#defined_class

Return 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 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 singleton class.

6th block parameter of Kernel.set_trace_func passes original class of attached by 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 'vm_trace.c', line 1118


static VALUE
tracepoint_attr_defined_class(VALUE tpval)
{
    return rb_tracearg_defined_class(get_trace_arg());
}

#disable ⇒ `Boolean` #disable ⇒ Object

Deactivates the trace

Return true if trace was enabled. Return false if 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 disable 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 'vm_trace.c', line 1458


static VALUE
tracepoint_disable_m(VALUE tpval)
{
    rb_tp_t *tp = tpptr(tpval);
    int previous_tracing = tp->tracing;

    if (rb_block_given_p()) {
        if (tp->local_target_set != Qfalse) {
            rb_raise(rb_eArgError, "can't disable a targetting TracePoint in a block");
        }

        rb_tracepoint_disable(tpval);
        return rb_ensure(rb_yield, Qundef,
			 previous_tracing ? rb_tracepoint_enable : rb_tracepoint_disable,
			 tpval);
    }
    else {
        rb_tracepoint_disable(tpval);
	return previous_tracing ? Qtrue : Qfalse;
    }
}

#enable(target: nil, target_line: nil, &blk)

[ GitHub ]

# File 'prelude.rb', line 136


def enable target: nil, target_line: nil, &blk
  self.__enable target, target_line, &blk
end

#eval_script

Compiled source code (String) on *eval methods on the :script_compiled event. If loaded from a file, it will return nil.

[ GitHub ]

# File 'vm_trace.c', line 1167


static VALUE
tracepoint_attr_eval_script(VALUE tpval)
{
    return rb_tracearg_eval_script(get_trace_arg());
}

#event

Type of event

See TracePoint@Events for more information.

[ GitHub ]

# File 'vm_trace.c', line 1033


static VALUE
tracepoint_attr_event(VALUE tpval)
{
    return rb_tracearg_event(get_trace_arg());
}

#inspect ⇒ String

Return a string containing a human-readable TracePoint status.

[ GitHub ]

# File 'vm_trace.c', line 1638


static VALUE
tracepoint_inspect(VALUE self)
{
    rb_tp_t *tp = tpptr(self);
    rb_trace_arg_t *trace_arg = GET_EC()->trace_arg;

    if (trace_arg) {
	switch (trace_arg->event) {
	  case RUBY_EVENT_LINE:
	    {
		VALUE sym = rb_tracearg_method_id(trace_arg);
		if (NIL_P(sym))
		    goto default_inspect;
		return rb_sprintf("#<TracePoint:%"PRIsVALUE"@%"PRIsVALUE":%d in `%"PRIsVALUE"'>",
				  rb_tracearg_event(trace_arg),
				  rb_tracearg_path(trace_arg),
				  FIX2INT(rb_tracearg_lineno(trace_arg)),
				  sym);
	    }
	  case RUBY_EVENT_CALL:
	  case RUBY_EVENT_C_CALL:
	  case RUBY_EVENT_RETURN:
	  case RUBY_EVENT_C_RETURN:
	    return rb_sprintf("#<TracePoint:%"PRIsVALUE" `%"PRIsVALUE"'@%"PRIsVALUE":%d>",
			      rb_tracearg_event(trace_arg),
			      rb_tracearg_method_id(trace_arg),
			      rb_tracearg_path(trace_arg),
			      FIX2INT(rb_tracearg_lineno(trace_arg)));
	  case RUBY_EVENT_THREAD_BEGIN:
	  case RUBY_EVENT_THREAD_END:
	    return rb_sprintf("#<TracePoint:%"PRIsVALUE" %"PRIsVALUE">",
			      rb_tracearg_event(trace_arg),
			      rb_tracearg_self(trace_arg));
	  default:
	  default_inspect:
	    return rb_sprintf("#<TracePoint:%"PRIsVALUE"@%"PRIsVALUE":%d>",
			      rb_tracearg_event(trace_arg),
			      rb_tracearg_path(trace_arg),
			      FIX2INT(rb_tracearg_lineno(trace_arg)));
	}
    }
    else {
	return rb_sprintf("#<TracePoint:%s>", tp->tracing ? "enabled" : "disabled");
    }
}

#instruction_sequence

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

Note that this method is MRI specific.

[ GitHub ]

# File 'vm_trace.c', line 1179


static VALUE
tracepoint_attr_instruction_sequence(VALUE tpval)
{
    return rb_tracearg_instruction_sequence(get_trace_arg());
}

#lineno

Line number of the event

[ GitHub ]

# File 'vm_trace.c', line 1042


static VALUE
tracepoint_attr_lineno(VALUE tpval)
{
    return rb_tracearg_lineno(get_trace_arg());
}

#method_id

Return the name at the definition of the method being called

[ GitHub ]

# File 'vm_trace.c', line 1069


static VALUE
tracepoint_attr_method_id(VALUE tpval)
{
    return rb_tracearg_method_id(get_trace_arg());
}

#parameters

Return the parameters of the method or block that the current hook belongs to

[ GitHub ]

# File 'vm_trace.c', line 1060


static VALUE
tracepoint_attr_parameters(VALUE tpval)
{
    return rb_tracearg_parameters(get_trace_arg());
}

#path

Path of the file being run

[ GitHub ]

# File 'vm_trace.c', line 1051


static VALUE
tracepoint_attr_path(VALUE tpval)
{
    return rb_tracearg_path(get_trace_arg());
}

#raised_exception

Value from exception raised on the :raise event

[ GitHub ]

# File 'vm_trace.c', line 1157


static VALUE
tracepoint_attr_raised_exception(VALUE tpval)
{
    return rb_tracearg_raised_exception(get_trace_arg());
}

#return_value

Return value from :return, c_return, and b_return event

[ GitHub ]

# File 'vm_trace.c', line 1148


static VALUE
tracepoint_attr_return_value(VALUE tpval)
{
    return rb_tracearg_return_value(get_trace_arg());
}

#self

Return the trace object during event

Same as #binding:

trace.binding.eval('self')

[ GitHub ]

# File 'vm_trace.c', line 1139


static VALUE
tracepoint_attr_self(VALUE tpval)
{
    return rb_tracearg_self(get_trace_arg());
}

Class: TracePoint

Overview

Example

Events

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(*events) {|obj| ... } ⇒ Object

Class Method Details

.stat ⇒ Object

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

Instance Attribute Details

#enabled? ⇒ Boolean (readonly)

Instance Method Details

#enable ⇒ Boolean #enable ⇒ Object

#binding

#callee_id

#defined_class

#disable ⇒ Boolean #disable ⇒ Object

#enable(target: nil, target_line: nil, &blk)

#eval_script

#event

#inspect ⇒ String

#instruction_sequence

#lineno

#method_id

#parameters

#path

#raised_exception

#return_value

#self

#enabled? ⇒ `Boolean` (readonly)

#enable ⇒ `Boolean` #enable ⇒ Object

#disable ⇒ `Boolean` #disable ⇒ Object