# class TracePoint

Document-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

`:script_compiled`

  new Ruby code compiled (with `eval`, `load` or `require`)

### 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.

    # File trace_point.rb, line 95
    def self.new(*events)
      Primitive.tracepoint_new_s(events)
    end

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.

    # File trace_point.rb, line 117
    def self.stat
      Primitive.tracepoint_stat_s
    end

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

Document-method: trace

    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

    # File trace_point.rb, line 134
    def self.trace(*events)
      Primitive.tracepoint_trace_s(events)
    end

### Public Instance Methods

binding() click to toggle source

Return the generated binding object from event

    # File trace_point.rb, line 313
    def binding
      Primitive.tracepoint_attr_binding
    end

callee_id() click to toggle source

Return the called name of the method being called

    # File trace_point.rb, line 272
    def callee_id
      Primitive.tracepoint_attr_callee_id
    end

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

    # File trace_point.rb, line 308
    def defined_class
      Primitive.tracepoint_attr_defined_class
    end

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

    # File trace_point.rb, line 231
    def disable
      Primitive.tracepoint_disable_m
    end

enable(target: nil, target_line: nil, target_thread: nil) → true or false click to toggle source
enable(target: nil, target_line: nil, target_thread: nil) { block } → obj

Activates the trace.

Returns `true` if trace was enabled. Returns `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

`target`, `target_line` and `target_thread` parameters are used to limit tracing only 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

    # File trace_point.rb, line 195
    def enable(target: nil, target_line: nil, target_thread: nil)
      Primitive.tracepoint_enable_m(target, target_line, target_thread)
    end

enabled? → true or false click to toggle source

The current status of the trace

    # File trace_point.rb, line 239
    def enabled?
      Primitive.tracepoint_enabled_p
    end

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.

    # File trace_point.rb, line 337
    def eval_script
      Primitive.tracepoint_attr_eval_script
    end

event() click to toggle source

Type of event

See Events at `TracePoint` for more information.

    # File trace_point.rb, line 246
    def event
      Primitive.tracepoint_attr_event
    end

inspect → string click to toggle source

Return a string containing a human-readable `TracePoint` status.

    # File trace_point.rb, line 104
    def inspect
      Primitive.tracepoint_inspect
    end

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.

    # File trace_point.rb, line 345
    def instruction_sequence
      Primitive.tracepoint_attr_instruction_sequence
    end

lineno() click to toggle source

Line number of the event

    # File trace_point.rb, line 251
    def lineno
      Primitive.tracepoint_attr_lineno
    end

method_id() click to toggle source

Return the name at the definition of the method being called

    # File trace_point.rb, line 267
    def method_id
      Primitive.tracepoint_attr_method_id
    end

parameters() click to toggle source

Return the parameters definition of the method or block that the current hook belongs to. Format is the same as for `Method#parameters`

    # File trace_point.rb, line 262
    def parameters
      Primitive.tracepoint_attr_parameters
    end

path() click to toggle source

Path of the file being run

    # File trace_point.rb, line 256
    def path
      Primitive.tracepoint_attr_path
    end

raised_exception() click to toggle source

Value from exception raised on the `:raise` event

    # File trace_point.rb, line 331
    def raised_exception
      Primitive.tracepoint_attr_raised_exception
    end

return_value() click to toggle source

Return value from `:return`, `c_return`, and `b_return` event

    # File trace_point.rb, line 326
    def return_value
      Primitive.tracepoint_attr_return_value
    end

self() click to toggle source

Return the trace object during event

Same as `TracePoint#binding`:

    trace.binding.eval('self')

    # File trace_point.rb, line 321
    def self
      Primitive.tracepoint_attr_self
    end