класс 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: обработчик событий при завершении потока

Публичные методы класса

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

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

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

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

Возвращает 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 { block } → 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, Qnil,
                         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.