Class: TracePoint (Ruby 2.3.4)

    In Files

    • vm_trace.c

    Class/Module Index [+]

    Quicksearch

    TracePoint

    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

    Public Class Methods

    new(*events) { |obj| block } → obj click to toggle source

    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 Events at TracePoint for possible events and more information.

    A block must be given, otherwise a ThreadError 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.line #=> access from outside (RuntimeError)
    

    Access from other threads is also forbidden.

     
                   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_eThreadError, "must be called with a block");
        }
    
        return tracepoint_new(self, 0, events, 0, 0, rb_block_proc());
    }
                
    stat → obj click to toggle source

    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.

     
                   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->event_hooks.hooks);
        /* TODO: thread local hooks */
    
        return stat;
    }
                
    trace(*events) { |obj| block } → obj click to toggle source

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

    trace = TracePoint.trace(:call) { |tp| [tp.lineno, tp.event] }
    #=> #<TracePoint:enabled>
    
    trace.enabled? #=> true
    
     
                   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;
    }
                

    Public Instance Methods

    binding() click to toggle source

    Return the generated binding object from event

     
                   static VALUE
    tracepoint_attr_binding(VALUE tpval)
    {
        return rb_tracearg_binding(get_trace_arg());
    }
                
    defined_class() click to toggle source

    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
    
     
                   static VALUE
    tracepoint_attr_defined_class(VALUE tpval)
    {
        return rb_tracearg_defined_class(get_trace_arg());
    }
                
    disable → true or false click to toggle source
    disable { block } → obj

    Deactivates the trace

    Return true if trace was enabled. Return false if trace was disabled.

    trace.enabled?       #=> true
    trace.disable        #=> false (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
    
     
                   static VALUE
    tracepoint_disable_m(VALUE tpval)
    {
        rb_tp_t *tp = tpptr(tpval);
        int previous_tracing = tp->tracing;
        rb_tracepoint_disable(tpval);
    
        if (rb_block_given_p()) {
            return rb_ensure(rb_yield, Qnil,
                             previous_tracing ? rb_tracepoint_enable : rb_tracepoint_disable,
                             tpval);
        }
        else {
            return previous_tracing ? Qtrue : Qfalse;
        }
    }
                
    enable → true or false click to toggle source
    enable { block } → obj

    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
    
     
                   static VALUE
    tracepoint_enable_m(VALUE tpval)
    {
        rb_tp_t *tp = tpptr(tpval);
        int previous_tracing = tp->tracing;
        rb_tracepoint_enable(tpval);
    
        if (rb_block_given_p()) {
            return rb_ensure(rb_yield, Qnil,
                             previous_tracing ? rb_tracepoint_enable : rb_tracepoint_disable,
                             tpval);
        }
        else {
            return previous_tracing ? Qtrue : Qfalse;
        }
    }
                
    enabled? → true or false click to toggle source

    The current status of the trace

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

    Type of event

    See Events at TracePoint for more information.

     
                   static VALUE
    tracepoint_attr_event(VALUE tpval)
    {
        return rb_tracearg_event(get_trace_arg());
    }
                
    inspect → string click to toggle source

    Return a string containing a human-readable TracePoint status.

     
                   static VALUE
    tracepoint_inspect(VALUE self)
    {
        rb_tp_t *tp = tpptr(self);
        rb_trace_arg_t *trace_arg = GET_THREAD()->trace_arg;
    
        if (trace_arg) {
            switch (trace_arg->event) {
              case RUBY_EVENT_LINE:
              case RUBY_EVENT_SPECIFIED_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");
        }
    }
                
    lineno() click to toggle source

    Line number of the event

     
                   static VALUE
    tracepoint_attr_lineno(VALUE tpval)
    {
        return rb_tracearg_lineno(get_trace_arg());
    }
                
    method_id() click to toggle source

    Return the name of the method being called

     
                   static VALUE
    tracepoint_attr_method_id(VALUE tpval)
    {
        return rb_tracearg_method_id(get_trace_arg());
    }
                
    path() click to toggle source

    Path of the file being run

     
                   static VALUE
    tracepoint_attr_path(VALUE tpval)
    {
        return rb_tracearg_path(get_trace_arg());
    }
                
    raised_exception() click to toggle source

    Value from exception raised on the :raise event

     
                   static VALUE
    tracepoint_attr_raised_exception(VALUE tpval)
    {
        return rb_tracearg_raised_exception(get_trace_arg());
    }
                
    return_value() click to toggle source

    Return value from :return, c_return, and b_return event

     
                   static VALUE
    tracepoint_attr_return_value(VALUE tpval)
    {
        return rb_tracearg_return_value(get_trace_arg());
    }
                
    self() click to toggle source

    Return the trace object during event

    Same as #binding:

    trace.binding.eval('self')
    
     
                   static VALUE
    tracepoint_attr_self(VALUE tpval)
    {
        return rb_tracearg_self(get_trace_arg());
    }