Class: TracePoint

Inherits:
Object show all
Defined in:
vm_trace.c,
vm_trace.c

Overview

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

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.new(*args) ⇒ Object

TracePoint.new(*events) { |obj| block } -> obj

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 TracePoint@Events for possible events and more information.

A block must be given, otherwise a ThreadError 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.line #=> access from outside (RuntimeError)

Access from other threads is also forbidden.



1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
 
# File 'vm_trace.c', line 1269

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

.stat ⇒ Object

TracePoint.stat -> obj

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.



1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
 
# File 'vm_trace.c', line 1384

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

.trace(*args) ⇒ Object

call-seq: TracePoint.trace(*events) { |obj| block } -> obj

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



1291
1292
1293
1294
1295
1296
1297
 
# File 'vm_trace.c', line 1291

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

Instance Method Details

#binding ⇒ Object

Return the generated binding object from event



960
961
962
963
964
 
# File 'vm_trace.c', line 960

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

#defined_class ⇒ Object

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



951
952
953
954
955
 
# File 'vm_trace.c', line 951

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

#disable ⇒ Object

trace.disable -> true or false trace.disable { block } -> obj

Deactivates the trace

Return true if trace was enabled. Return false if trace was disabled.

trace.enabled? #=> true trace.disable #=> false (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



1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
 
# File 'vm_trace.c', line 1133

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

#enable ⇒ Object

trace.enable -> true or false trace.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



1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
 
# File 'vm_trace.c', line 1082

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

#enabled? ⇒ Boolean

trace.enabled? -> true or false

The current status of the trace

Returns:

  • (Boolean) 


1156
1157
1158
1159
1160
1161
 
# File 'vm_trace.c', line 1156

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

#event ⇒ Object

Type of event

See TracePoint@Events for more information.



884
885
886
887
888
 
# File 'vm_trace.c', line 884

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

#inspect ⇒ String

Return a string containing a human-readable TracePoint status.

Returns:



1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
 
# File 'vm_trace.c', line 1307

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

#lineno ⇒ Object

Line number of the event



893
894
895
896
897
 
# File 'vm_trace.c', line 893

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

#method_id ⇒ Object

Return the name of the method being called



911
912
913
914
915
 
# File 'vm_trace.c', line 911

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

#path ⇒ Object

Path of the file being run



902
903
904
905
906
 
# File 'vm_trace.c', line 902

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

#raised_exception ⇒ Object

Value from exception raised on the :raise event



990
991
992
993
994
 
# File 'vm_trace.c', line 990

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

#return_value ⇒ Object

Return value from :return, c_return, and b_return event



981
982
983
984
985
 
# File 'vm_trace.c', line 981

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

#self ⇒ Object

Return the trace object during event

Same as TracePoint#binding: trace.binding.eval(‘self’)



972
973
974
975
976
 
# File 'vm_trace.c', line 972

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