# class 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 `TracePoint#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 `TracePoint#disable`

    trace.disable

See Events at `TracePoint` 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.

    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());
    }

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->global_hooks.hooks);
        /* TODO: thread local hooks */

        return stat;
    }

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

A convenience method for `TracePoint.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

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, 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() 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());
    }

callee_id() click to toggle source

Return the called name of the method being called

    static VALUE
    tracepoint_attr_callee_id(VALUE tpval)
    {
        return rb_tracearg_callee_id(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        #=> 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

    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) click to toggle source

    # File prelude.rb, line 136
    def enable target: nil, target_line: nil, &blk
      self.__enable target, target_line, &blk
    end

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;
    }

eval_script() click to toggle source

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

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

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_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() click to toggle source

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

Note that this method is MRI specific.

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

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 at the definition of the method being called

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

parameters() click to toggle source

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

    static VALUE
    tracepoint_attr_parameters(VALUE tpval)
    {
        return rb_tracearg_parameters(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 `TracePoint#binding`:

    trace.binding.eval('self')

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