Ruby: include/ruby/debug.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

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

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

## Postponed Job API
typedef void(* | rb_postponed_job_func_t) (void *arg)
| Type of postponed jobs.
int | rb_postponed_job_register (unsigned int flags, rb_postponed_job_func_t func, void *data)
| Registers a postponed job.
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.

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

## ◆ RB_DEBUG_INSPECTOR_FRAME_DEPTH

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

Value:
rb_debug_inspector_frame_depth(dc, index)
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.
Definition vm_backtrace.c:1556

Definition at line 277 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 198 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 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] | arg | What was passed to rb_postponed_job_register().

Definition at line 608 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 445 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 1570 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 1563 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 1540 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 1533 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 1556 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 1547 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 1526 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 1485 of file vm_backtrace.c.

Referenced by rb_debug_inspector_open().

## ◆ 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] | func | Job body.
  [in,out] | data | Passed as-is to `func`.

Return values

  0 | Postponed job buffer is full. Failed.
  otherwise | Opaque return value.

Postcondition
  The passed job is postponed.

Definition at line 1685 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_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] | func | Job body.
  [in,out] | data | Passed as-is to `func`.

Return values

  0 | Postponed job buffer is full. Failed.
  otherwise | Opaque return value.

Definition at line 1704 of file vm_trace.c.

Referenced by rb_postponed_job_register_one().

## ◆ 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 1688 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 1710 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 1739 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 1717 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 1808 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 1703 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 1768 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 1656 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 1800 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 1760 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 1576 of file vm_backtrace.c.

Referenced by rb_profile_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 299 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 179 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 281 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 287 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 956 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 942 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 949 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 847 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 841 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 835 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 861 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 935 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 1062 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 867 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 996 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 981 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 975 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 1287 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 1169 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 1410 of file vm_trace.c.

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

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:1440
RUBY_INTERNAL_EVENT_FREEOBJ
#define RUBY_INTERNAL_EVENT_FREEOBJ
Object swept.
Definition event.h:89
RUBY_INTERNAL_EVENT_NEWOBJ
#define RUBY_INTERNAL_EVENT_NEWOBJ
Object allocated.
Definition event.h:88
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 1440 of file vm_trace.c.