класс 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 будет включать все доступные события.

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

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

: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_eThreadError, "must be called with a block");
    }

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

Возвращает новый объект 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]
# ...

Для деактивации отслеживания, необходимо использовать #disable

trace.disable

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

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

Если метод отслеживания не включён в заданный фильтр событий, генерируется исключение 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.line #=> 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->event_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;
}

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

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

trace.enabled? #=> true

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

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 возвращает синглтон-класс.

Шестой параметр блока 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 { блок } → obj

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, Qundef,
                         previous_tracing ? rb_tracepoint_enable : rb_tracepoint_disable,
                         tpval);
    }
    else {
        return previous_tracing ? Qtrue : Qfalse;
    }
}

Деактивирует отслеживание

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

trace.enabled?       #=> true
trace.disable        #=> false (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 → true или false Показать исходный код

enable { блок } → obj

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

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

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

Текущий статус отслеживания

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

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

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

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

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

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

То же, что и #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.