класс TracePoint

Родитель:: Объект

Класс, предоставляющий функциональность Kernel#set_trace_func в удобном объектно-ориентированном API.

Пример

Мы можем использовать TracePoint для сбора информации, специфичной для исключений:

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

События

Если вы не указываете тип событий, на которые хотите подписываться, TracePoint будет включать все доступные события.

Примечание не полагайтесь на текущий набор событий, так как этот список может изменяться. Вместо этого рекомендуется указать тип событий, которые вы хотите использовать.

Для фильтрации отслеживаемых событий вы можете передать любое из следующих значений events:

:line: выполнение кода на новой строке
:class: начало определения класса или модуля
:end: окончание определения класса или модуля
:call: вызов метода Ruby
:return: возврат из метода Ruby
:c_call: вызов C-функции
:c_return: возврат из C-функции
:raise: выбрасывание исключения
:b_call: обработчик события при входе в блок
:b_return: обработчик события при выходе из блока
:thread_begin: обработчик события при запуске потока
:thread_end: обработчик события при завершении потока
:fiber_switch: обработчик события при переключении волокна

Методы публичного класса

new(*events) { |obj| block } → obj Показать исходный код

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

Возвращает новый объект TracePoint, по умолчанию не включённый.

Далее, для активации трассировки, необходимо использовать 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]
# ...

При желании деактивировать трассировку, необходимо использовать TracePoint#disable.

trace.disable

См. События по адресу TracePoint для возможных событий и дополнительной информации.

Блок должен быть задан, в противном случае будет поднято исключение ArgumentError.

Если метод трассировки не включён в заданный фильтр событий, будет поднято исключение RuntimeError.

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

Если метод трассировки вызывается вне блока, будет поднято исключение RuntimeError.

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

Доступ из других потоков также запрещён.

stat → obj Показать исходный код

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

Возвращает внутреннюю информацию об объекте TracePoint.

Содержание возвращаемого значения зависит от реализации. Оно может быть изменено в будущем.

Этот метод предназначен только для отладки самого объекта TracePoint.

trace(*events) { |obj| block } → obj Показать исходный код

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

Удобный метод для TracePoint.new, автоматически активирующий трассировку.

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

trace.enabled? #=> true

Методы публичного экземпляра

enable → true или false Показать исходный код

enable { block } → obj

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

Активирует трассировку

Возвращает true, если трассировка была включена. Возвращает false, если трассировка была выключена.

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

Если задан блок, трассировка будет включена только в рамках этого блока.

trace.enabled?
#=> false

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

trace.enabled?
#=> false

Примечание: Вы не можете получить доступ к обработчикам событий внутри блока.

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

binding() Показать исходный код

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

Возвращает сгенерированный объект связывания из события

callee_id() Показать исходный код

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

Возвращает имя вызываемого метода

defined_class() Показать исходный код

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

Возвращает класс или модуль вызываемого метода.

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

Если метод определён модулем, возвращается этот модуль.

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

Примечание: defined_class возвращает класс-синглтон.

6-й параметр блока Kernel#set_trace_func передаёт исходный класс, прикреплённый классом-синглтоном.

Это различие между Kernel#set_trace_func и 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

disable → true или false Показать исходный код

disable { block } → obj

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

Деактивирует трассировку

Возвращает true, если трассировка была включена. Возвращает false, если трассировка была выключена.

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

Если задан блок, трассировка будет выключена только в рамках этого блока.

trace.enabled?
#=> true

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

trace.enabled?
#=> true

Примечание: Вы не можете получить доступ к обработчикам событий внутри блока.

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

enable(target: nil, target_line: nil, &blk) Показать исходный код

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

enabled? → true или false Показать исходный код

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

Текущий статус трассировки

eval_script() Показать исходный код

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

Компилированный исходный код (строка) для *eval-методов в событии :script_compiled. Если загружено из файла, возвращает nil.

event() Показать исходный код

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

Тип события

См. События по адресу TracePoint для дополнительной информации.

inspect → строка Показать исходный код

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

Возвращает строку, содержащую удобочитаемый статус объекта TracePoint.

instruction_sequence() Показать исходный код

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

Компилированная последовательность инструкций, представленная экземпляром RubyVM::InstructionSequence в событии :script_compiled.

Обратите внимание, что этот метод специфичен для MRI.

lineno() Показать исходный код

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

Номер строки события

method_id() Показать исходный код

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

Возвращает имя метода в точке его определения

parameters() Показать исходный код

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

Возвращает параметры метода или блока, к которому относится текущий обработчик

path() Показать исходный код

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

Путь к файлу, который выполняется

raised_exception() Показать исходный код

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

Значение исключения, поднятого в событии :raise

return_value() Показать исходный код

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

Возвращаемое значение из события :return, c_return, и b_return

self() Показать исходный код

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

Возвращает объект трассировки во время события

То же самое, что и TracePoint#binding:

trace.binding.eval('self')

Ruby Core © 1993–2017 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.