Ruby: include/ruby/debug.h File Reference

Ruby 3.4.8p72 (2025-12-17 revision 995b59f66677d44767ce9faac6957e5543617ff9)

debug.h File Reference
`#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"`
Include dependency graph for debug.h:
This graph shows which files directly or indirectly include this file:

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.
int | rb_profile_thread_frames (VALUE thread, int start, int limit, VALUE *buff, int *lines)
| Queries mysterious "frame"s of the given range.
VALUE | rb_profile_frame_path (VALUE frame)
| Queries the path of the passed backtrace.
VALUE | rb_profile_frame_absolute_path (VALUE frame)
| Identical to rb_profile_frame_path(), except it tries to expand the returning path.
VALUE | rb_profile_frame_label (VALUE frame)
| Queries human-readable "label" string.
VALUE | rb_profile_frame_base_label (VALUE frame)
| Identical to rb_profile_frame_label(), except it does not "qualify" the result.
VALUE | rb_profile_frame_full_label (VALUE frame)
| Identical to rb_profile_frame_label(), except it returns a qualified result.
VALUE | rb_profile_frame_first_lineno (VALUE frame)
| Queries the first line of the method of the passed frame pointer.
VALUE | rb_profile_frame_classpath (VALUE frame)
| Queries the class path of the method that the passed frame represents.
VALUE | rb_profile_frame_singleton_method_p (VALUE frame)
| Queries if the method of the passed frame is a singleton class.
VALUE | rb_profile_frame_method_name (VALUE frame)
| Queries the name of the method of the passed frame.
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.
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.
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.
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.
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.

## 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.
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().
VALUE | rb_debug_inspector_open (rb_debug_inspector_func_t func, void *data)
| Prepares, executes, then cleans up a debug session.
VALUE | rb_debug_inspector_backtrace_locations (const rb_debug_inspector_t *dc)
| Queries the backtrace object of the context.
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.
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.
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.
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.
VALUE | rb_debug_inspector_frame_depth (const rb_debug_inspector_t *dc, long index)
| Queries the depth of the passed context's upper frame.
VALUE | rb_debug_inspector_current_depth (void)
| Return current frmae depth.

## 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.
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`
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.
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.
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.
int | rb_postponed_job_register_one (unsigned int flags, rb_postponed_job_func_t func, void *data)
| Identical to `rb_postponed_job_register`

## TracePoint APIs
typedef struct rb_trace_arg_struct | rb_trace_arg_t
| Type that represents a specific trace event.
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.
VALUE | rb_tracepoint_enable (VALUE tpval)
| Starts (enables) trace(s) defined by the passed object.
VALUE | rb_tracepoint_disable (VALUE tpval)
| Stops (disables) an already running instance of TracePoint.
VALUE | rb_tracepoint_enabled_p (VALUE tpval)
| Queries if the passed TracePoint is up and running.
rb_trace_arg_t * | rb_tracearg_from_tracepoint (VALUE tpval)
| Queries the current event of the passed tracepoint.
rb_event_flag_t | rb_tracearg_event_flag (rb_trace_arg_t *trace_arg)
| Queries the event of the passed trace.
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.
VALUE | rb_tracearg_lineno (rb_trace_arg_t *trace_arg)
| Queries the line of the point where the trace is at.
VALUE | rb_tracearg_path (rb_trace_arg_t *trace_arg)
| Queries the file name of the point where the trace is at.
VALUE | rb_tracearg_method_id (rb_trace_arg_t *trace_arg)
| Queries the method name of the point where the trace is at.
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().
VALUE | rb_tracearg_defined_class (rb_trace_arg_t *trace_arg)
| Queries the class that defines the method that the passed trace is at.
VALUE | rb_tracearg_binding (rb_trace_arg_t *trace_arg)
| Creates a binding object of the point where the trace is at.
VALUE | rb_tracearg_self (rb_trace_arg_t *trace_arg)
| Queries the receiver of the point trace is at.
VALUE | rb_tracearg_return_value (rb_trace_arg_t *trace_arg)
| Queries the return value that the trace represents.
VALUE | rb_tracearg_raised_exception (rb_trace_arg_t *trace_arg)
| Queries the raised exception that the trace represents.
VALUE | rb_tracearg_object (rb_trace_arg_t *trace_arg)
| Queries the allocated/deallocated object that the trace represents.

## Detailed Description

Author

Author
  ko1

Date
  Tue Nov 20 20:35:08 2012

Copyright
  Copyright (C) 2012 Yukihiro Matsumoto
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Definition in file debug.h.

## Macro Definition Documentation

## ◆ POSTPONED_JOB_HANDLE_INVALID

#define POSTPONED_JOB_HANDLE_INVALID ((rb_postponed_job_handle_t)UINT_MAX)

Definition at line 666 of file debug.h.

## ◆ RB_DEBUG_INSPECTOR_FRAME_DEPTH

#define RB_DEBUG_INSPECTOR_FRAME_DEPTH | ( |  | dc,
|  |  | index
| ) |  | rb_debug_inspector_frame_depth(dc, index)

Definition at line 297 of 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] | dc | A debug context.
  [in,out] | data | What was passed to rb_debug_inspector_open().

Returns
  What would be the return value of rb_debug_inspector_open().

Definition at line 218 of file debug.h.

## ◆ rb_debug_inspector_t

typedef struct rb_debug_inspector_struct rb_debug_inspector_t

Opaque struct representing a debug inspector.

Definition at line 207 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] | arg | What was passed to `rb_postponed_job_preregister`

Definition at line 659 of file debug.h.

## ◆ rb_postponed_job_handle_t

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`

Definition at line 665 of file debug.h.

## ◆ rb_trace_arg_t

typedef struct rb_trace_arg_struct 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 465 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] | dc | A debug context.

Returns
  An array of `Thread::Backtrace::Location` which represents the current point of execution at `dc`.

Definition at line 1702 of file vm_backtrace.c.

Referenced by rb_debug_inspector_backtrace_locations().

## ◆ rb_debug_inspector_current_depth()

VALUE rb_debug_inspector_current_depth | ( | void |  | ) |

Return current frmae depth.

Return values

  The | depth of the current frame in Integer.

Definition at line 1695 of file vm_backtrace.c.

Referenced by rb_debug_inspector_current_depth().

## ◆ 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] | dc | A debug context.
  [in] | index | Index of the frame from top to bottom.

Exceptions

  rb_eArgError | `index` out of range.

Returns
  The binding at `index`-th frame.

Definition at line 1672 of file vm_backtrace.c.

Referenced by rb_debug_inspector_frame_binding_get().

## ◆ 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] | dc | A debug context.
  [in] | index | Index of the frame from top to bottom.

Exceptions

  rb_eArgError | `index` out of range.

Returns
  The current class at `index`-th frame.

Definition at line 1665 of file vm_backtrace.c.

Referenced by rb_debug_inspector_frame_class_get().

## ◆ rb_debug_inspector_frame_depth()

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.

Parameters

  [in] | dc | A debug context.
  [in] | index | Index of the frame from top to bottom.

Exceptions

  rb_eArgError | `index` out of range.

Return values

  The | depth at `index`-th frame in Integer.

Definition at line 1688 of file vm_backtrace.c.

Referenced by rb_debug_inspector_frame_depth().

## ◆ 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] | dc | A debug context.
  [in] | index | Index of the frame from top to bottom.

Exceptions

  rb_eArgError | `index` out of range.

Return values

  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.

Referenced by rb_debug_inspector_frame_iseq_get().

## ◆ 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] | dc | A debug context.
  [in] | index | Index of the frame from top to bottom.

Exceptions

  rb_eArgError | `index` out of range.

Returns
  The current receiver at `index`-th frame.

Definition at line 1658 of file vm_backtrace.c.

Referenced by rb_debug_inspector_frame_self_get().

## ◆ 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] | func | A callback to run inside of a debug session.
  [in,out] | data | Passed as-is to `func`.

Returns
  What was returned from `func`.

Definition at line 1617 of file vm_backtrace.c.

Referenced by rb_debug_inspector_open().

## ◆ rb_postponed_job_preregister()

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.

Parameters

  [in] | flags | Unused and ignored
  [in] | func | The function to be pre-registered
  [in] | data | The data to be pre-registered

Return values

  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 1753 of file vm_trace.c.

Referenced by rb_postponed_job_preregister().

## ◆ rb_postponed_job_register()

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:

rb_postponed_job_trigger(rb_postponed_job_preregister(func, data));
rb_postponed_job_trigger
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 executi...
Definition vm_trace.c:1787
rb_postponed_job_preregister
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 ...
Definition vm_trace.c:1753

Note
  Previous versions of Ruby promised that the (`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.

Deprecated:
  This interface implies that arbitrarily many `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.

Parameters

  [in] | flags | Unused and ignored.
  [in] | func | Job body.
  [in,out] | data | Passed as-is to `func`.

Return values

  0 | Postponed job registration table is full. Failed.
  1 | Registration succeeded.

Postcondition
  The passed job will run on the next interrupt check.

Definition at line 1811 of file vm_trace.c.

Referenced by rb_postponed_job_register().

## ◆ 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`

Deprecated:
  This is deprecated for the same reason as `rb_postponed_job_register`

Parameters

  [in] | flags | Unused and ignored.
  [in] | func | Job body.
  [in,out] | data | Passed as-is to `func`.

Return values

  0 | Postponed job registration table is full. Failed.
  1 | Registration succeeded.

Postcondition
  The passed job will run on the next interrupt check.

Definition at line 1817 of file vm_trace.c.

Referenced by rb_postponed_job_register_one().

## ◆ rb_postponed_job_trigger()

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 1787 of file vm_trace.c.

Referenced by rb_postponed_job_trigger().

## ◆ 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] | frame | What rb_profile_frames() returned.

Return values

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

Referenced by rb_profile_frame_absolute_path().

## ◆ 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] | frame | What rb_profile_frames() returned.

Return values

  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_base_label(), and 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] | frame | What rb_profile_frames() returned.

Return values

  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.

Referenced by rb_profile_frame_classpath().

## ◆ 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] | frame | What rb_profile_frames() returned.

Return values

  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.

Referenced by rb_profile_frame_first_lineno().

## ◆ 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] | frame | What rb_profile_frames() returned.

Return values

  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.

Referenced by rb_profile_frame_full_label().

## ◆ 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] | frame | What rb_profile_frames() returned.

Return values

  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(), and rb_profile_frame_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] | frame | What rb_profile_frames() returned.

Return values

  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_method_name(), and 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] | frame | What rb_profile_frames() returned.

Return values

  RUBY_Qnil | The frame is implemented in C etc.
  otherwise | Where `frame` is running.

Definition at line 1823 of file vm_backtrace.c.

Referenced by rb_profile_frame_path().

## ◆ 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] | frame | What rb_profile_frames() returned.

Return values

  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(), and rb_profile_frame_qualified_method_name().

## ◆ 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] | frame | What rb_profile_frames() returned.

Return values

  RUBY_Qtrue | It is a singleton method.
  RUBY_Qfalse | Otherwise (normal method/non-method).

Definition at line 1927 of file vm_backtrace.c.

Referenced by rb_profile_frame_singleton_method_p().

## ◆ 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] | start | Start position (0 means the topmost).
  [in] | limit | Number objects of `buff`.
  [out] | buff | Return buffer.
  [out] | lines | Return 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 1776 of file vm_backtrace.c.

Referenced by rb_profile_frames().

## ◆ rb_profile_thread_frames()

int rb_profile_thread_frames | ( | VALUE | thread,
|  | int | start,
|  | int | limit,
|  | VALUE * | buff,
|  | int * | lines
| ) |  |

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.

Parameters

  [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.

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 1790 of file vm_backtrace.c.

Referenced by rb_profile_thread_frames().

## ◆ 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] | func | A callback.
  [in] | data | What 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 321 of file vm_trace.c.

Referenced by rb_remove_event_hook_with_data(), and 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] | 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`.

Exceptions

  rb_eTypeError | `thval` is not a thread.

Definition at line 201 of file vm_trace.c.

Referenced by rb_thread_add_event_hook().

## ◆ 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] | thval | An instance of rb_cThread.
  [in] | func | A callback.

Exceptions

  rb_eTypeError | `thval` 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 303 of file vm_trace.c.

Referenced by rb_thread_remove_event_hook().

## ◆ 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] | thval | An instance of rb_cThread.
  [in] | func | A callback.
  [in] | data | What to be passed to `func`.

Exceptions

  rb_eTypeError | `thval` 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 309 of file vm_trace.c.

Referenced by rb_thread_remove_event_hook_with_data(), and 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_arg | A trace instance.

Return values

  RUBY_Qnil | The point has no binding.
  otherwise | Its binding.

Definition at line 982 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_arg | A trace instance.

Return values

  RUBY_Qnil | There is no method.
  otherwise | Its method name, in Ruby level Symbol.

Definition at line 968 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_arg | A trace instance.

Return values

  RUBY_Qnil | There is no method.
  otherwise | Its method's class.

Definition at line 975 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_arg | A trace instance.

Returns
  Its event, in Ruby level Symbol object.

Definition at line 869 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_arg | A trace instance.

Returns
  Its event.

Definition at line 863 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] | tpval | An instance of TracePoint.

Exceptions

  rb_eRuntimeError | `tpval` is disabled.

Returns
  The current event.

Definition at line 857 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_arg | A trace instance.

Return values

  0 | The trace is not at Ruby frame.

Returns
  otherwise Its line number.

Definition at line 883 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_arg | A trace instance.

Return values

  RUBY_Qnil | There is no method.
  otherwise | Its method name, in Ruby level Symbol.

Definition at line 961 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_arg | A trace instance.

Exceptions

  rb_eRuntimeError | The tracing event is not GC-related.

Returns
  The allocated/deallocated object.

Definition at line 1088 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_arg | A trace instance.

Return values

  RUBY_Qnil | The trace is not at Ruby frame.
  otherwise | Its path.

Definition at line 889 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_arg | A trace instance.

Exceptions

  rb_eRuntimeError | The tracing event is not exception-related.

Returns
  The raised exception.

Definition at line 1022 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_arg | A trace instance.

Exceptions

  rb_eRuntimeError | The tracing event is not return-related.

Returns
  The return value.

Definition at line 1007 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_arg | A trace instance.

Returns
  Its receiver.

Definition at line 1001 of file vm_trace.c.

## ◆ rb_tracepoint_disable()

VALUE rb_tracepoint_disable | ( | VALUE | tpval | ) |

Stops (disables) an already running instance of TracePoint.

Parameters

  [in] | tpval | An instance of TracePoint.

Returns
  Undefined value. Forget this. It should have returned `void`.

Postcondition
  Trace(s) defined by `tpval` stop.

Definition at line 1321 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] | tpval | An instance of TracePoint.

Exceptions

  rb_eArgError | A trace is already running.

Returns
  Undefined value. Forget this. It should have returned `void`.

Postcondition
  Trace(s) defined by `tpval` start.

Definition at line 1195 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] | tpval | An instance of TracePoint.

Return values

  RUBY_Qtrue | It is.
  RUBY_Qfalse | It isn't.

Definition at line 1447 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_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:

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:

rb_tracepoint_new(
Qnil,
RUBY_INTERNAL_EVENT_NEWOBJ | RUBY_INTERNAL_EVENT_FREEOBJ,
obj_event_i,
data);
rb_tracepoint_new
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:1477
RUBY_INTERNAL_EVENT_FREEOBJ
#define RUBY_INTERNAL_EVENT_FREEOBJ
Object swept.
Definition event.h:94
RUBY_INTERNAL_EVENT_NEWOBJ
#define RUBY_INTERNAL_EVENT_NEWOBJ
Object allocated.
Definition event.h:93
Qnil
#define Qnil
Old name of RUBY_Qnil.
Definition special_consts.h:60

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 1477 of file vm_trace.c.