Ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e0ba6b95ab71a441357ed5484e33498)
debug.h File Reference
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/attr/returns_nonnull.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/event.h"
#include "ruby/internal/value.h"

Go to the source code of this file.

Functions

Frame-profiling APIs
int rb_profile_frames (int start, int limit, VALUE *buff, int *lines)
 Queries mysterious "frame"s of the given range. More...
 
VALUE rb_profile_frame_path (VALUE frame)
 Queries the path of the passed backtrace. More...
 
VALUE rb_profile_frame_absolute_path (VALUE frame)
 Identical to rb_profile_frame_path(), except it tries to expand the returning path. More...
 
VALUE rb_profile_frame_label (VALUE frame)
 Queries human-readable "label" string. More...
 
VALUE rb_profile_frame_base_label (VALUE frame)
 Identical to rb_profile_frame_label(), except it does not "qualify" the result. More...
 
VALUE rb_profile_frame_full_label (VALUE frame)
 Identical to rb_profile_frame_label(), except it returns a qualified result. More...
 
VALUE rb_profile_frame_first_lineno (VALUE frame)
 Queries the first line of the method of the passed frame pointer. More...
 
VALUE rb_profile_frame_classpath (VALUE frame)
 Queries the class path of the method that the passed frame represents. More...
 
VALUE rb_profile_frame_singleton_method_p (VALUE frame)
 Queries if the method of the passed frame is a singleton class. More...
 
VALUE rb_profile_frame_method_name (VALUE frame)
 Queries the name of the method of the passed frame. More...
 
VALUE rb_profile_frame_qualified_method_name (VALUE frame)
 Identical to rb_profile_frame_method_name(), except it "qualifies" the return value with its defining class. More...
 
Old style set_trace_func APIs
int rb_remove_event_hook_with_data (rb_event_hook_func_t func, VALUE data)
 Identical to rb_remove_event_hook(), except it additionally takes the data argument. More...
 
void rb_thread_add_event_hook (VALUE thval, rb_event_hook_func_t func, rb_event_flag_t events, VALUE data)
 Identical to rb_add_event_hook(), except its effect is limited to the passed thread. More...
 
int rb_thread_remove_event_hook (VALUE thval, rb_event_hook_func_t func)
 Identical to rb_remove_event_hook(), except it additionally takes a thread argument. More...
 
int rb_thread_remove_event_hook_with_data (VALUE thval, rb_event_hook_func_t func, VALUE data)
 Identical to rb_thread_remove_event_hook(), except it additionally takes the data argument. More...
 

Debug inspector APIs

typedef struct rb_debug_inspector_struct rb_debug_inspector_t
 Opaque struct representing a debug inspector. More...
 
typedef VALUE(* rb_debug_inspector_func_t) (const rb_debug_inspector_t *dc, void *data)
 Type of the callback function passed to rb_debug_inspector_open(). More...
 
VALUE rb_debug_inspector_open (rb_debug_inspector_func_t func, void *data)
 Prepares, executes, then cleans up a debug session. More...
 
VALUE rb_debug_inspector_frame_self_get (const rb_debug_inspector_t *dc, long index)
 Queries the current receiver of the passed context's upper frame. More...
 
VALUE rb_debug_inspector_frame_class_get (const rb_debug_inspector_t *dc, long index)
 Queries the current class of the passed context's upper frame. More...
 
VALUE rb_debug_inspector_frame_binding_get (const rb_debug_inspector_t *dc, long index)
 Queries the binding of the passed context's upper frame. More...
 
VALUE rb_debug_inspector_frame_iseq_get (const rb_debug_inspector_t *dc, long index)
 Queries the instruction sequence of the passed context's upper frame. More...
 
VALUE rb_debug_inspector_backtrace_locations (const rb_debug_inspector_t *dc)
 Queries the backtrace object of the context. More...
 

TracePoint APIs

typedef struct rb_trace_arg_struct rb_trace_arg_t
 Type that represents a specific trace event. More...
 
VALUE rb_tracepoint_new (VALUE target_thread_not_supported_yet, rb_event_flag_t events, void(*func)(VALUE, void *), void *data)
 Creates a tracepoint by registering a callback function for one or more tracepoint events. More...
 
VALUE rb_tracepoint_enable (VALUE tpval)
 Starts (enables) trace(s) defined by the passed object. More...
 
VALUE rb_tracepoint_disable (VALUE tpval)
 Stops (disables) an already running instance of TracePoint. More...
 
VALUE rb_tracepoint_enabled_p (VALUE tpval)
 Queries if the passed TracePoint is up and running. More...
 
rb_trace_arg_trb_tracearg_from_tracepoint (VALUE tpval)
 Queries the current event of the passed tracepoint. More...
 
rb_event_flag_t rb_tracearg_event_flag (rb_trace_arg_t *trace_arg)
 Queries the event of the passed trace. More...
 
VALUE rb_tracearg_event (rb_trace_arg_t *trace_arg)
 Identical to rb_tracearg_event_flag(), except it returns the name of the event in Ruby's symbol. More...
 
VALUE rb_tracearg_lineno (rb_trace_arg_t *trace_arg)
 Queries the line of the point where the trace is at. More...
 
VALUE rb_tracearg_path (rb_trace_arg_t *trace_arg)
 Queries the file name of the point where the trace is at. More...
 
VALUE rb_tracearg_method_id (rb_trace_arg_t *trace_arg)
 Queries the method name of the point where the trace is at. More...
 
VALUE rb_tracearg_callee_id (rb_trace_arg_t *trace_arg)
 Identical to rb_tracearg_method_id(), except it returns callee id like rb_frame_callee(). More...
 
VALUE rb_tracearg_defined_class (rb_trace_arg_t *trace_arg)
 Queries the class that defines the method that the passed trace is at. More...
 
VALUE rb_tracearg_binding (rb_trace_arg_t *trace_arg)
 Creates a binding object of the point where the trace is at. More...
 
VALUE rb_tracearg_self (rb_trace_arg_t *trace_arg)
 Queries the receiver of the point trace is at. More...
 
VALUE rb_tracearg_return_value (rb_trace_arg_t *trace_arg)
 Queries the return value that the trace represents. More...
 
VALUE rb_tracearg_raised_exception (rb_trace_arg_t *trace_arg)
 Queries the raised exception that the trace represents. More...
 
VALUE rb_tracearg_object (rb_trace_arg_t *trace_arg)
 Queries the allocated/deallocated object that the trace represents. More...
 

Postponed Job API

typedef void(* rb_postponed_job_func_t) (void *arg)
 Type of postponed jobs. More...
 
int rb_postponed_job_register (unsigned int flags, rb_postponed_job_func_t func, void *data)
 Registers a postponed job. More...
 
int rb_postponed_job_register_one (unsigned int flags, rb_postponed_job_func_t func, void *data)
 Identical to rb_postponed_job_register_one(), except it additionally checks for duplicated registration. More...
 

Detailed Description

Author
Author
ko1
Date
Tue Nov 20 20:35:08 2012

Definition in file debug.h.

Typedef Documentation

◆ rb_debug_inspector_func_t

typedef VALUE(* rb_debug_inspector_func_t) (const rb_debug_inspector_t *dc, void *data)

Type of the callback function passed to rb_debug_inspector_open().

Inspection shall happen only inside of them. The passed pointers gets invalidated once after the callback returns.

Parameters
[in]dcA debug context.
[in,out]dataWhat was passed to rb_debug_inspector_open().
Returns
What would be the return value of rb_debug_inspector_open().

Definition at line 198 of file debug.h.

◆ rb_debug_inspector_t

Opaque struct representing a debug inspector.

Definition at line 187 of file debug.h.

◆ rb_postponed_job_func_t

typedef void(* rb_postponed_job_func_t) (void *arg)

Type of postponed jobs.

Parameters
[in,out]argWhat was passed to rb_postponed_job_register().

Definition at line 585 of file debug.h.

◆ rb_trace_arg_t

Type that represents a specific trace event.

Roughly resembles the tracepoint object that is passed to the block of TracePoint.new:

TracePoint.new(*events) do |obj|
... # ^^^^^ Resembles this object.
end

Definition at line 422 of file debug.h.

Function Documentation

◆ rb_debug_inspector_backtrace_locations()

VALUE rb_debug_inspector_backtrace_locations ( const rb_debug_inspector_t dc)

Queries the backtrace object of the context.

This is as if you call caller_locations at the point of debugger.

Parameters
[in]dcA debug context.
Returns
An array of Thread::Backtrace::Location which represents the current point of execution at dc.

Definition at line 1507 of file vm_backtrace.c.

◆ rb_debug_inspector_frame_binding_get()

VALUE rb_debug_inspector_frame_binding_get ( const rb_debug_inspector_t dc,
long  index 
)

Queries the binding of the passed context's upper frame.

Parameters
[in]dcA debug context.
[in]indexIndex of the frame from top to bottom.
Exceptions
rb_eArgErrorindex out of range.
Returns
The binding at index-th frame.

Definition at line 1491 of file vm_backtrace.c.

◆ rb_debug_inspector_frame_class_get()

VALUE rb_debug_inspector_frame_class_get ( const rb_debug_inspector_t dc,
long  index 
)

Queries the current class of the passed context's upper frame.

Parameters
[in]dcA debug context.
[in]indexIndex of the frame from top to bottom.
Exceptions
rb_eArgErrorindex out of range.
Returns
The current class at index-th frame.

Definition at line 1484 of file vm_backtrace.c.

◆ rb_debug_inspector_frame_iseq_get()

VALUE rb_debug_inspector_frame_iseq_get ( const rb_debug_inspector_t dc,
long  index 
)

Queries the instruction sequence of the passed context's upper frame.

Parameters
[in]dcA debug context.
[in]indexIndex of the frame from top to bottom.
Exceptions
rb_eArgErrorindex out of range.
Return values
RUBY_Qnilindex-th frame is not in Ruby (C etc.).
otherwiseAn instance of RubyVM::InstructionSequence which represents the instruction sequence at index-th frame.

Definition at line 1498 of file vm_backtrace.c.

◆ rb_debug_inspector_frame_self_get()

VALUE rb_debug_inspector_frame_self_get ( const rb_debug_inspector_t dc,
long  index 
)

Queries the current receiver of the passed context's upper frame.

Parameters
[in]dcA debug context.
[in]indexIndex of the frame from top to bottom.
Exceptions
rb_eArgErrorindex out of range.
Returns
The current receiver at index-th frame.

Definition at line 1477 of file vm_backtrace.c.

◆ rb_debug_inspector_open()

VALUE rb_debug_inspector_open ( rb_debug_inspector_func_t  func,
void *  data 
)

Prepares, executes, then cleans up a debug session.

Parameters
[in]funcA callback to run inside of a debug session.
[in,out]dataPassed as-is to func.
Returns
What was returned from func.

Definition at line 1436 of file vm_backtrace.c.

◆ rb_postponed_job_register()

int rb_postponed_job_register ( unsigned int  flags,
rb_postponed_job_func_t  func,
void *  data 
)

Registers a postponed job.

There are situations when running a ruby program is not possible. For instance when a program is in a signal handler; for another instance when the GC is busy. On such situations however, there might be needs to do something. We cannot but defer such operations until we are 100% sure it is safe to execute them. This mechanism is called postponed jobs. This function registers a new one. The registered job would eventually gets executed.

Parameters
[in]flags(Unused) reserved for future extensions.
[in]funcJob body.
[in,out]dataPassed as-is to func.
Return values
0Postponed job buffer is full. Failed.
otherwiseOpaque return value.
Postcondition
The passed job is postponed.

Definition at line 1634 of file vm_trace.c.

◆ rb_postponed_job_register_one()

int rb_postponed_job_register_one ( unsigned int  flags,
rb_postponed_job_func_t  func,
void *  data 
)

Identical to rb_postponed_job_register_one(), except it additionally checks for duplicated registration.

In case the passed job is already in the postponed job buffer this function does nothing.

Parameters
[in]flags(Unused) reserved for future extensions.
[in]funcJob body.
[in,out]dataPassed as-is to func.
Return values
0Postponed job buffer is full. Failed.
otherwiseOpaque return value.

Definition at line 1653 of file vm_trace.c.

◆ rb_profile_frame_absolute_path()

VALUE rb_profile_frame_absolute_path ( VALUE  frame)

Identical to rb_profile_frame_path(), except it tries to expand the returning path.

In case the path is require-d from something else rb_profile_frame_path() can return relative paths. This one tries to avoid that.

Parameters
[in]frameWhat rb_profile_frames() returned.
Return values
<cfunc>The frame is in C.
RUBY_QnilCan't infer real path (inside of eval etc.).
otherwiseWhere frame is running.

Definition at line 1613 of file vm_backtrace.c.

◆ rb_profile_frame_base_label()

VALUE rb_profile_frame_base_label ( VALUE  frame)

Identical to rb_profile_frame_label(), except it does not "qualify" the result.

Consider the following backtrace:

def bar
caller_locations
end
def foo
[1].map { bar }.first
end
obj = foo.first
obj.label # => "block in foo"
obj.base_label # => "foo"
Parameters
[in]frameWhat rb_profile_frames() returned.
Return values
RUBY_QnilCan't infer the label (C etc.).
<main>The frame is global toplevel.
<compiled>The frame is dynamic.
otherwiseBase label of the frame.

Definition at line 1635 of file vm_backtrace.c.

Referenced by rb_profile_frame_full_label().

◆ rb_profile_frame_classpath()

VALUE rb_profile_frame_classpath ( VALUE  frame)

Queries the class path of the method that the passed frame represents.

Parameters
[in]frameWhat rb_profile_frames() returned.
Return values
RUBY_QnilCan't infer the class (global toplevel etc.).
otherwiseClass path as in rb_class_path().

Definition at line 1664 of file vm_backtrace.c.

◆ rb_profile_frame_first_lineno()

VALUE rb_profile_frame_first_lineno ( VALUE  frame)

Queries the first line of the method of the passed frame pointer.

Can be handy when for instance a debugger want to display the frame in question.

Parameters
[in]frameWhat rb_profile_frames() returned.
Return values
RUBY_QnilCan't infer the line (C etc.).
otherwiseLine number of the method in question.

Definition at line 1642 of file vm_backtrace.c.

◆ rb_profile_frame_full_label()

VALUE rb_profile_frame_full_label ( VALUE  frame)

Identical to rb_profile_frame_label(), except it returns a qualified result.

Parameters
[in]frameWhat rb_profile_frames() returned.
Return values
RUBY_QnilCan't infer the label (C etc.).
<main>The frame is global toplevel.
<compiled>The frame is dynamic.
otherwiseQualified label of the frame.

Definition at line 1733 of file vm_backtrace.c.

◆ rb_profile_frame_label()

VALUE rb_profile_frame_label ( VALUE  frame)

Queries human-readable "label" string.

This is "<main>" for the toplevel, "<compiled>" for evaluated ones, method name for methods, class name for classes.

Parameters
[in]frameWhat rb_profile_frames() returned.
Return values
RUBY_QnilCan't infer the label (C etc.).
<main>The frame is global toplevel.
<compiled>The frame is dynamic.
otherwiseLabel of the frame.

Definition at line 1628 of file vm_backtrace.c.

Referenced by rb_profile_frame_full_label().

◆ rb_profile_frame_method_name()

VALUE rb_profile_frame_method_name ( VALUE  frame)

Queries the name of the method of the passed frame.

Parameters
[in]frameWhat rb_profile_frames() returned.
Return values
RUBY_QnilThe frame in question is not a method.
otherwiseName of the method of the frame.

Definition at line 1693 of file vm_backtrace.c.

Referenced by rb_profile_frame_qualified_method_name().

◆ rb_profile_frame_path()

VALUE rb_profile_frame_path ( VALUE  frame)

Queries the path of the passed backtrace.

Parameters
[in]frameWhat rb_profile_frames() returned.
Return values
RUBY_QnilThe frame is implemented in C etc.
otherwiseWhere frame is running.

Definition at line 1581 of file vm_backtrace.c.

◆ rb_profile_frame_qualified_method_name()

VALUE rb_profile_frame_qualified_method_name ( VALUE  frame)

Identical to rb_profile_frame_method_name(), except it "qualifies" the return value with its defining class.

Parameters
[in]frameWhat rb_profile_frames() returned.
Return values
RUBY_QnilThe frame in question is not a method.
otherwiseQualified name of the method of the frame.

Definition at line 1725 of file vm_backtrace.c.

Referenced by rb_profile_frame_full_label().

◆ rb_profile_frame_singleton_method_p()

VALUE rb_profile_frame_singleton_method_p ( VALUE  frame)

Queries if the method of the passed frame is a singleton class.

Parameters
[in]frameWhat rb_profile_frames() returned.
Return values
RUBY_QtrueIt is a singleton method.
RUBY_QfalseOtherwise (normal method/non-method).

Definition at line 1685 of file vm_backtrace.c.

◆ rb_profile_frames()

int rb_profile_frames ( int  start,
int  limit,
VALUE buff,
int *  lines 
)

Queries mysterious "frame"s of the given range.

The returned values are opaque backtrace pointers, which you are allowed to issue a very limited set of operations listed below. Don't call arbitrary ruby methods.

Parameters
[in]startStart position (0 means the topmost).
[in]limitNumber objects of buff.
[out]buffReturn buffer.
[out]linesReturn buffer.
Returns
Number of objects filled into buff.
Postcondition
buff is filled with backtrace pointers.
lines is filled with __LINE__ of each backtraces.

Definition at line 1513 of file vm_backtrace.c.

◆ rb_remove_event_hook_with_data()

int rb_remove_event_hook_with_data ( rb_event_hook_func_t  func,
VALUE  data 
)

Identical to rb_remove_event_hook(), except it additionally takes the data argument.

This extra argument is the same as that of rb_add_event_hook(), and this function removes the hook which matches both arguments at once.

Parameters
[in]funcA callback.
[in]dataWhat to be passed to func.
Returns
Number of deleted event hooks.
Note
As multiple events can share the same func it is quite possible for the return value to become more than one.

Definition at line 298 of file vm_trace.c.

Referenced by rb_tracepoint_disable().

◆ rb_thread_add_event_hook()

void rb_thread_add_event_hook ( VALUE  thval,
rb_event_hook_func_t  func,
rb_event_flag_t  events,
VALUE  data 
)

Identical to rb_add_event_hook(), except its effect is limited to the passed thread.

Other threads are not affected by this.

Parameters
[in]thvalAn instance of rb_cThread.
[in]funcA callback.
[in]eventsA set of events that func should run.
[in]dataPassed as-is to func.
Exceptions
rb_eTypeErrorthval is not a thread.

Definition at line 178 of file vm_trace.c.

◆ rb_thread_remove_event_hook()

int rb_thread_remove_event_hook ( VALUE  thval,
rb_event_hook_func_t  func 
)

Identical to rb_remove_event_hook(), except it additionally takes a thread argument.

This extra argument is the same as that of rb_thread_add_event_hook(), and this function removes the hook which matches both arguments at once.

Parameters
[in]thvalAn instance of rb_cThread.
[in]funcA callback.
Exceptions
rb_eTypeErrorthval is not a thread.
Returns
Number of deleted event hooks.
Note
As multiple events can share the same func it is quite possible for the return value to become more than one.

Definition at line 280 of file vm_trace.c.

◆ rb_thread_remove_event_hook_with_data()

int rb_thread_remove_event_hook_with_data ( VALUE  thval,
rb_event_hook_func_t  func,
VALUE  data 
)

Identical to rb_thread_remove_event_hook(), except it additionally takes the data argument.

It can also be seen as a routine identical to rb_remove_event_hook_with_data(), except it additionally takes the thread. This function deletes hooks that satisfy all three criteria.

Parameters
[in]thvalAn instance of rb_cThread.
[in]funcA callback.
[in]dataWhat to be passed to func.
Exceptions
rb_eTypeErrorthval is not a thread.
Returns
Number of deleted event hooks.
Note
As multiple events can share the same func it is quite possible for the return value to become more than one.

Definition at line 286 of file vm_trace.c.

Referenced by rb_tracepoint_disable().

◆ rb_tracearg_binding()

VALUE rb_tracearg_binding ( rb_trace_arg_t trace_arg)

Creates a binding object of the point where the trace is at.

Parameters
[in]trace_argA trace instance.
Return values
RUBY_QnilThe point has no binding.
otherwiseIts binding.

Definition at line 948 of file vm_trace.c.

◆ rb_tracearg_callee_id()

VALUE rb_tracearg_callee_id ( rb_trace_arg_t trace_arg)

Identical to rb_tracearg_method_id(), except it returns callee id like rb_frame_callee().

Parameters
[in]trace_argA trace instance.
Return values
RUBY_QnilThere is no method.
otherwiseIts method name, in Ruby level Symbol.

Definition at line 934 of file vm_trace.c.

◆ rb_tracearg_defined_class()

VALUE rb_tracearg_defined_class ( rb_trace_arg_t trace_arg)

Queries the class that defines the method that the passed trace is at.

This can be different from the class of rb_tracearg_self()'s return value because of inheritance(s).

Parameters
[in]trace_argA trace instance.
Return values
RUBY_QnilThere is no method.
otherwiseIts method's class.

Definition at line 941 of file vm_trace.c.

◆ rb_tracearg_event()

VALUE rb_tracearg_event ( rb_trace_arg_t trace_arg)

Identical to rb_tracearg_event_flag(), except it returns the name of the event in Ruby's symbol.

Parameters
[in]trace_argA trace instance.
Returns
Its event, in Ruby level Symbol object.

Definition at line 839 of file vm_trace.c.

◆ rb_tracearg_event_flag()

rb_event_flag_t rb_tracearg_event_flag ( rb_trace_arg_t trace_arg)

Queries the event of the passed trace.

Parameters
[in]trace_argA trace instance.
Returns
Its event.

Definition at line 833 of file vm_trace.c.

◆ rb_tracearg_from_tracepoint()

rb_trace_arg_t * rb_tracearg_from_tracepoint ( VALUE  tpval)

Queries the current event of the passed tracepoint.

Parameters
[in]tpvalAn instance of TracePoint.
Exceptions
rb_eRuntimeErrortpval is disabled.
Returns
The current event.

Definition at line 827 of file vm_trace.c.

◆ rb_tracearg_lineno()

VALUE rb_tracearg_lineno ( rb_trace_arg_t trace_arg)

Queries the line of the point where the trace is at.

Parameters
[in]trace_argA trace instance.
Return values
0The trace is not at Ruby frame.
Returns
otherwise Its line number.

Definition at line 853 of file vm_trace.c.

◆ rb_tracearg_method_id()

VALUE rb_tracearg_method_id ( rb_trace_arg_t trace_arg)

Queries the method name of the point where the trace is at.

Parameters
[in]trace_argA trace instance.
Return values
RUBY_QnilThere is no method.
otherwiseIts method name, in Ruby level Symbol.

Definition at line 927 of file vm_trace.c.

◆ rb_tracearg_object()

VALUE rb_tracearg_object ( rb_trace_arg_t trace_arg)

Queries the allocated/deallocated object that the trace represents.

Parameters
[in]trace_argA trace instance.
Exceptions
rb_eRuntimeErrorThe tracing event is not GC-related.
Returns
The allocated/deallocated object.

Definition at line 1049 of file vm_trace.c.

◆ rb_tracearg_path()

VALUE rb_tracearg_path ( rb_trace_arg_t trace_arg)

Queries the file name of the point where the trace is at.

Parameters
[in]trace_argA trace instance.
Return values
RUBY_QnilThe trace is not at Ruby frame.
otherwiseIts path.

Definition at line 859 of file vm_trace.c.

◆ rb_tracearg_raised_exception()

VALUE rb_tracearg_raised_exception ( rb_trace_arg_t trace_arg)

Queries the raised exception that the trace represents.

Parameters
[in]trace_argA trace instance.
Exceptions
rb_eRuntimeErrorThe tracing event is not exception-related.
Returns
The raised exception.

Definition at line 983 of file vm_trace.c.

◆ rb_tracearg_return_value()

VALUE rb_tracearg_return_value ( rb_trace_arg_t trace_arg)

Queries the return value that the trace represents.

Parameters
[in]trace_argA trace instance.
Exceptions
rb_eRuntimeErrorThe tracing event is not return-related.
Returns
The return value.

Definition at line 968 of file vm_trace.c.

◆ rb_tracearg_self()

VALUE rb_tracearg_self ( rb_trace_arg_t trace_arg)

Queries the receiver of the point trace is at.

Parameters
[in]trace_argA trace instance.
Returns
Its receiver.

Definition at line 962 of file vm_trace.c.

◆ rb_tracepoint_disable()

VALUE rb_tracepoint_disable ( VALUE  tpval)

Stops (disables) an already running instance of TracePoint.

Parameters
[in]tpvalAn instance of TracePoint.
Returns
Undefined value. Forget this. It should have returned void.
Postcondition
Trace(s) defined by tpval stop.

Definition at line 1270 of file vm_trace.c.

◆ rb_tracepoint_enable()

VALUE rb_tracepoint_enable ( VALUE  tpval)

Starts (enables) trace(s) defined by the passed object.

A TracePoint object does not immediately take effect on creation. You have to explicitly call this API.

Parameters
[in]tpvalAn instance of TracePoint.
Exceptions
rb_eArgErrorA trace is already running.
Returns
Undefined value. Forget this. It should have returned void.
Postcondition
Trace(s) defined by tpval start.

Definition at line 1156 of file vm_trace.c.

◆ rb_tracepoint_enabled_p()

VALUE rb_tracepoint_enabled_p ( VALUE  tpval)

Queries if the passed TracePoint is up and running.

Parameters
[in]tpvalAn instance of TracePoint.
Return values
RUBY_QtrueIt is.
RUBY_QfalseIt isn't.

Definition at line 1384 of file vm_trace.c.

◆ rb_tracepoint_new()

VALUE rb_tracepoint_new ( VALUE  target_thread_not_supported_yet,
rb_event_flag_t  events,
void(*)(VALUE, void *)  func,
void *  data 
)

Creates a tracepoint by registering a callback function for one or more tracepoint events.

Once the tracepoint is created, you can use rb_tracepoint_enable to enable the tracepoint.

Parameters
[in]target_thread_not_supported_yetMeant for picking the thread in which the tracepoint is to be created. However, current implementation ignore this parameter, tracepoint is created for all threads. Simply specify Qnil.
[in]eventsEvent(s) to listen to.
[in]funcA callback function.
[in,out]dataVoid pointer that will be passed to the callback function.

When the callback function is called, it will be passed 2 parameters:

  1. VALUE tpval - the TracePoint object from which trace args can be extracted.
  1. void *data - A void pointer which helps to share scope with the callback function.

It is important to note that you cannot register callbacks for normal events and internal events simultaneously because they are different purpose. You can use any Ruby APIs (calling methods and so on) on normal event hooks. However, in internal events, you can not use any Ruby APIs (even object creations). This is why we can't specify internal events by TracePoint directly. Limitations are MRI version specific.

Example:

obj_event_i,
data);
VALUE rb_tracepoint_new(VALUE target_thread_not_supported_yet, rb_event_flag_t events, void(*func)(VALUE, void *), void *data)
Creates a tracepoint by registering a callback function for one or more tracepoint events.
Definition: vm_trace.c:1414
#define RUBY_INTERNAL_EVENT_FREEOBJ
Object swept.
Definition: event.h:89
#define RUBY_INTERNAL_EVENT_NEWOBJ
Object allocated.
Definition: event.h:88
#define Qnil
Old name of RUBY_Qnil.

In this example, a callback function obj_event_i will be registered for internal events RUBY_INTERNAL_EVENT_NEWOBJ and RUBY_INTERNAL_EVENT_FREEOBJ.

Definition at line 1414 of file vm_trace.c.