Ruby
3.4.0dev (2024-11-22 revision 0989400a925cd201defdca9eb28eb87200b30785)
|
#include "ruby/internal/attr/deprecated.h"
#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... | |
int | rb_profile_thread_frames (VALUE thread, 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 | |
#define | RB_DEBUG_INSPECTOR_FRAME_DEPTH(dc, index) rb_debug_inspector_frame_depth(dc, index) |
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_backtrace_locations (const rb_debug_inspector_t *dc) |
Queries the backtrace object of the context. 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_frame_depth (const rb_debug_inspector_t *dc, long index) |
Queries the depth of the passed context's upper frame. More... | |
VALUE | rb_debug_inspector_current_depth (void) |
Return current frmae depth. More... | |
Postponed Job API | |
#define | POSTPONED_JOB_HANDLE_INVALID ((rb_postponed_job_handle_t)UINT_MAX) |
typedef void(* | rb_postponed_job_func_t) (void *arg) |
Type of postponed jobs. More... | |
typedef unsigned int | rb_postponed_job_handle_t |
The type of a handle returned from rb_postponed_job_preregister and passed to rb_postponed_job_trigger More... | |
rb_postponed_job_handle_t | rb_postponed_job_preregister (unsigned int flags, rb_postponed_job_func_t func, void *data) |
Pre-registers a func in Ruby's postponed job preregistration table, returning an opaque handle which can be used to trigger the job later. More... | |
void | rb_postponed_job_trigger (rb_postponed_job_handle_t h) |
Triggers a pre-registered job registered with rb_postponed_job_preregister, scheduling it for execution the next time the Ruby VM checks for interrupts. More... | |
int | rb_postponed_job_register (unsigned int flags, rb_postponed_job_func_t func, void *data) |
Schedules the given func to be called with data when Ruby next checks for interrupts. More... | |
int | rb_postponed_job_register_one (unsigned int flags, rb_postponed_job_func_t func, void *data) |
Identical to rb_postponed_job_register 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_t * | rb_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... | |
Definition in file debug.h.
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.
[in] | dc | A debug context. |
[in,out] | data | What was passed to rb_debug_inspector_open(). |
typedef struct rb_debug_inspector_struct rb_debug_inspector_t |
typedef void(* rb_postponed_job_func_t) (void *arg) |
typedef unsigned int rb_postponed_job_handle_t |
typedef struct rb_trace_arg_struct rb_trace_arg_t |
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.
[in] | dc | A debug context. |
Thread::Backtrace::Location
which represents the current point of execution at dc
. Definition at line 1702 of file vm_backtrace.c.
VALUE rb_debug_inspector_current_depth | ( | void | ) |
Return current frmae depth.
The | depth of the current frame in Integer. |
Definition at line 1695 of file vm_backtrace.c.
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.
[in] | dc | A debug context. |
[in] | index | Index of the frame from top to bottom. |
rb_eArgError | index out of range. |
index
-th frame. Definition at line 1672 of file vm_backtrace.c.
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.
[in] | dc | A debug context. |
[in] | index | Index of the frame from top to bottom. |
rb_eArgError | index out of range. |
index
-th frame. Definition at line 1665 of file vm_backtrace.c.
VALUE rb_debug_inspector_frame_depth | ( | const rb_debug_inspector_t * | dc, |
long | index | ||
) |
Queries the depth of the passed context's upper frame.
Note that the depth is not same as the frame index because debug_inspector skips some special frames but the depth counts all frames.
[in] | dc | A debug context. |
[in] | index | Index of the frame from top to bottom. |
rb_eArgError | index out of range. |
The | depth at index -th frame in Integer. |
Definition at line 1688 of file vm_backtrace.c.
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.
[in] | dc | A debug context. |
[in] | index | Index of the frame from top to bottom. |
rb_eArgError | index out of range. |
RUBY_Qnil | index -th frame is not in Ruby (C etc.). |
otherwise | An instance of RubyVM::InstructionSequence which represents the instruction sequence at index -th frame. |
Definition at line 1679 of file vm_backtrace.c.
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.
[in] | dc | A debug context. |
[in] | index | Index of the frame from top to bottom. |
rb_eArgError | index out of range. |
index
-th frame. Definition at line 1658 of file vm_backtrace.c.
VALUE rb_debug_inspector_open | ( | rb_debug_inspector_func_t | func, |
void * | data | ||
) |
Prepares, executes, then cleans up a debug session.
[in] | func | A callback to run inside of a debug session. |
[in,out] | data | Passed as-is to func . |
func
. Definition at line 1617 of file vm_backtrace.c.
rb_postponed_job_handle_t rb_postponed_job_preregister | ( | unsigned int | flags, |
rb_postponed_job_func_t | func, | ||
void * | data | ||
) |
Pre-registers a func in Ruby's postponed job preregistration table, returning an opaque handle which can be used to trigger the job later.
Generally, this function will be called during the initialization routine of an extension.
The returned handle can be used later to call rb_postponed_job_trigger
. This will cause Ruby to call back into the registered func
with data
at a later time, in a context where the GVL is held and it is safe to perform Ruby allocations.
If the given func
was already pre-registered, this function will overwrite the stored data with the newly passed data, and return the same handle instance as was previously returned.
If this function is called concurrently with the same func
, then the stored data could be the value from either call (but will definitely be one of them).
If this function is called to update the data concurrently with a call to rb_postponed_job_trigger
on the same handle, it's undefined whether func
will be called with the old data or the new data.
Although the current implementation of this function is in fact async-signal-safe and has defined semantics when called concurrently on the same func
, a future Ruby version might require that this method be called under the GVL; thus, programs which aim to be forward-compatible should call this method whilst holding the GVL.
[in] | flags | Unused and ignored |
[in] | func | The function to be pre-registered |
[in] | data | The data to be pre-registered |
POSTPONED_JOB_HANDLE_INVALID | The job table is full; this registration did not succeed and no further registration will do so for the lifetime of the program. |
otherwise | A handle which can be passed to rb_postponed_job_trigger |
Definition at line 1749 of file vm_trace.c.
int rb_postponed_job_register | ( | unsigned int | flags, |
rb_postponed_job_func_t | func, | ||
void * | data | ||
) |
Schedules the given func
to be called with data
when Ruby next checks for interrupts.
If this function is called multiple times in between Ruby checking for interrupts, then func
will be called only once with the data
value from the first call to this function.
Like rb_postponed_job_trigger
, the context in which the job is called holds the GVL and can allocate Ruby objects.
This method essentially has the same semantics as:
func
, data
) pairs would be executed as many times as they were registered with this function; in reality this was always subject to race conditions and this function no longer provides this guarantee. Instead, multiple calls to this function can be coalesced into a single execution of the passed func
, with the most recent data
registered at that time passed in.func
's can be enqueued over the lifetime of the program, whilst in reality the registration slots for postponed jobs are a finite resource. This is made clearer by the rb_postponed_job_preregister
and rb_postponed_job_trigger
functions, and a future version of Ruby might delete this function.[in] | flags | Unused and ignored. |
[in] | func | Job body. |
[in,out] | data | Passed as-is to func . |
0 | Postponed job registration table is full. Failed. |
1 | Registration succeeded. |
Definition at line 1807 of file vm_trace.c.
int rb_postponed_job_register_one | ( | unsigned int | flags, |
rb_postponed_job_func_t | func, | ||
void * | data | ||
) |
Identical to rb_postponed_job_register
rb_postponed_job_register
[in] | flags | Unused and ignored. |
[in] | func | Job body. |
[in,out] | data | Passed as-is to func . |
0 | Postponed job registration table is full. Failed. |
1 | Registration succeeded. |
Definition at line 1813 of file vm_trace.c.
void rb_postponed_job_trigger | ( | rb_postponed_job_handle_t | h | ) |
Triggers a pre-registered job registered with rb_postponed_job_preregister, scheduling it for execution the next time the Ruby VM checks for interrupts.
The context in which the job is called in holds the GVL and is safe to perform Ruby allocations within (i.e. it is not during GC).
This method is async-signal-safe and can be called from any thread, at any time, including in signal handlers.
If this method is called multiple times, Ruby will coalesce this into only one call to the job the next time it checks for interrupts.
@params[in] h A handle returned from rb_postponed_job_preregister
Definition at line 1783 of file vm_trace.c.
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.
[in] | frame | What rb_profile_frames() returned. |
<cfunc> | The frame is in C. |
RUBY_Qnil | Can't infer real path (inside of eval etc.). |
otherwise | Where frame is running. |
Definition at line 1855 of file vm_backtrace.c.
Identical to rb_profile_frame_label(), except it does not "qualify" the result.
Consider the following backtrace:
[in] | frame | What rb_profile_frames() returned. |
RUBY_Qnil | Can't infer the label (C etc.). |
<main> | The frame is global toplevel. |
<compiled> | The frame is dynamic. |
otherwise | Base label of the frame. |
Definition at line 1877 of file vm_backtrace.c.
Referenced by rb_profile_frame_full_label().
Queries the class path of the method that the passed frame represents.
[in] | frame | What rb_profile_frames() returned. |
RUBY_Qnil | Can't infer the class (global toplevel etc.). |
otherwise | Class path as in rb_class_path(). |
Definition at line 1906 of file vm_backtrace.c.
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.
[in] | frame | What rb_profile_frames() returned. |
RUBY_Qnil | Can't infer the line (C etc.). |
otherwise | Line number of the method in question. |
Definition at line 1884 of file vm_backtrace.c.
Identical to rb_profile_frame_label(), except it returns a qualified result.
[in] | frame | What rb_profile_frames() returned. |
RUBY_Qnil | Can't infer the label (C etc.). |
<main> | The frame is global toplevel. |
<compiled> | The frame is dynamic. |
otherwise | Qualified label of the frame. |
Definition at line 1975 of file vm_backtrace.c.
Queries human-readable "label" string.
This is "<main>"
for the toplevel, "<compiled>"
for evaluated ones, method name for methods, class name for classes.
[in] | frame | What rb_profile_frames() returned. |
RUBY_Qnil | Can't infer the label (C etc.). |
<main> | The frame is global toplevel. |
<compiled> | The frame is dynamic. |
otherwise | Label of the frame. |
Definition at line 1870 of file vm_backtrace.c.
Referenced by rb_profile_frame_full_label().
Queries the name of the method of the passed frame.
[in] | frame | What rb_profile_frames() returned. |
RUBY_Qnil | The frame in question is not a method. |
otherwise | Name of the method of the frame. |
Definition at line 1935 of file vm_backtrace.c.
Referenced by rb_profile_frame_qualified_method_name().
Queries the path of the passed backtrace.
[in] | frame | What rb_profile_frames() returned. |
RUBY_Qnil | The frame is implemented in C etc. |
otherwise | Where frame is running. |
Definition at line 1823 of file vm_backtrace.c.
Identical to rb_profile_frame_method_name(), except it "qualifies" the return value with its defining class.
[in] | frame | What rb_profile_frames() returned. |
RUBY_Qnil | The frame in question is not a method. |
otherwise | Qualified name of the method of the frame. |
Definition at line 1967 of file vm_backtrace.c.
Referenced by rb_profile_frame_full_label().
Queries if the method of the passed frame is a singleton class.
[in] | frame | What rb_profile_frames() returned. |
RUBY_Qtrue | It is a singleton method. |
RUBY_Qfalse | Otherwise (normal method/non-method). |
Definition at line 1927 of file vm_backtrace.c.
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.
[in] | start | Start position (0 means the topmost). |
[in] | limit | Number objects of buff . |
[out] | buff | Return buffer. |
[out] | lines | Return buffer. |
buff
. buff
is filled with backtrace pointers. lines
is filled with __LINE__
of each backtraces. Definition at line 1776 of file vm_backtrace.c.
Queries mysterious "frame"s of the given range.
A per-thread version of rb_profile_frames(). Arguments and return values are the same with rb_profile_frames() with the exception of the first argument thread, which accepts the Thread to be profiled/queried.
[in] | thread | The Ruby Thread to be profiled. |
[in] | start | Start position (0 means the topmost). |
[in] | limit | Number objects of buff . |
[out] | buff | Return buffer. |
[out] | lines | Return buffer. |
buff
. buff
is filled with backtrace pointers. lines
is filled with __LINE__
of each backtraces. Definition at line 1790 of file vm_backtrace.c.
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.
[in] | func | A callback. |
[in] | data | What to be passed to func . |
func
it is quite possible for the return value to become more than one. Definition at line 321 of file vm_trace.c.
Referenced by rb_tracepoint_disable().
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.
[in] | thval | An instance of rb_cThread. |
[in] | func | A callback. |
[in] | events | A set of events that func should run. |
[in] | data | Passed as-is to func . |
rb_eTypeError | thval is not a thread. |
Definition at line 201 of file vm_trace.c.
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.
[in] | thval | An instance of rb_cThread. |
[in] | func | A callback. |
rb_eTypeError | thval is not a thread. |
func
it is quite possible for the return value to become more than one. Definition at line 303 of file vm_trace.c.
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.
[in] | thval | An instance of rb_cThread. |
[in] | func | A callback. |
[in] | data | What to be passed to func . |
rb_eTypeError | thval is not a thread. |
func
it is quite possible for the return value to become more than one. Definition at line 309 of file vm_trace.c.
Referenced by rb_tracepoint_disable().
VALUE rb_tracearg_binding | ( | rb_trace_arg_t * | trace_arg | ) |
Creates a binding object of the point where the trace is at.
[in] | trace_arg | A trace instance. |
RUBY_Qnil | The point has no binding. |
otherwise | Its binding. |
Definition at line 978 of file vm_trace.c.
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().
[in] | trace_arg | A trace instance. |
RUBY_Qnil | There is no method. |
otherwise | Its method name, in Ruby level Symbol. |
Definition at line 964 of file vm_trace.c.
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).
[in] | trace_arg | A trace instance. |
RUBY_Qnil | There is no method. |
otherwise | Its method's class. |
Definition at line 971 of file vm_trace.c.
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.
[in] | trace_arg | A trace instance. |
Definition at line 868 of file vm_trace.c.
rb_event_flag_t rb_tracearg_event_flag | ( | rb_trace_arg_t * | trace_arg | ) |
Queries the event of the passed trace.
[in] | trace_arg | A trace instance. |
Definition at line 862 of file vm_trace.c.
rb_trace_arg_t* rb_tracearg_from_tracepoint | ( | VALUE | tpval | ) |
Queries the current event of the passed tracepoint.
[in] | tpval | An instance of TracePoint. |
rb_eRuntimeError | tpval is disabled. |
Definition at line 856 of file vm_trace.c.
VALUE rb_tracearg_lineno | ( | rb_trace_arg_t * | trace_arg | ) |
Queries the line of the point where the trace is at.
[in] | trace_arg | A trace instance. |
0 | The trace is not at Ruby frame. |
Definition at line 882 of file vm_trace.c.
VALUE rb_tracearg_method_id | ( | rb_trace_arg_t * | trace_arg | ) |
Queries the method name of the point where the trace is at.
[in] | trace_arg | A trace instance. |
RUBY_Qnil | There is no method. |
otherwise | Its method name, in Ruby level Symbol. |
Definition at line 957 of file vm_trace.c.
VALUE rb_tracearg_object | ( | rb_trace_arg_t * | trace_arg | ) |
Queries the allocated/deallocated object that the trace represents.
[in] | trace_arg | A trace instance. |
rb_eRuntimeError | The tracing event is not GC-related. |
Definition at line 1084 of file vm_trace.c.
VALUE rb_tracearg_path | ( | rb_trace_arg_t * | trace_arg | ) |
Queries the file name of the point where the trace is at.
[in] | trace_arg | A trace instance. |
RUBY_Qnil | The trace is not at Ruby frame. |
otherwise | Its path. |
Definition at line 888 of file vm_trace.c.
VALUE rb_tracearg_raised_exception | ( | rb_trace_arg_t * | trace_arg | ) |
Queries the raised exception that the trace represents.
[in] | trace_arg | A trace instance. |
rb_eRuntimeError | The tracing event is not exception-related. |
Definition at line 1018 of file vm_trace.c.
VALUE rb_tracearg_return_value | ( | rb_trace_arg_t * | trace_arg | ) |
Queries the return value that the trace represents.
[in] | trace_arg | A trace instance. |
rb_eRuntimeError | The tracing event is not return-related. |
Definition at line 1003 of file vm_trace.c.
VALUE rb_tracearg_self | ( | rb_trace_arg_t * | trace_arg | ) |
Queries the receiver of the point trace is at.
[in] | trace_arg | A trace instance. |
Definition at line 997 of file vm_trace.c.
Stops (disables) an already running instance of TracePoint.
[in] | tpval | An instance of TracePoint. |
void
. tpval
stop. Definition at line 1317 of file vm_trace.c.
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.
[in] | tpval | An instance of TracePoint. |
rb_eArgError | A trace is already running. |
void
. tpval
start. Definition at line 1191 of file vm_trace.c.
Queries if the passed TracePoint is up and running.
[in] | tpval | An instance of TracePoint. |
RUBY_Qtrue | It is. |
RUBY_Qfalse | It isn't. |
Definition at line 1443 of file vm_trace.c.
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.
[in] | target_thread_not_supported_yet | Meant 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] | events | Event(s) to listen to. |
[in] | func | A callback function. |
[in,out] | data | Void pointer that will be passed to the callback function. |
When the callback function is called, it will be passed 2 parameters:
VALUE tpval
- the TracePoint object from which trace args can be extracted.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:
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 1473 of file vm_trace.c.