Ruby: include/ruby/debug.h Source File

Ruby 4.0.5p0 (2026-05-20 revision 64336ffd0ee9e1f4c05891695a3d7b49cb709721)

debug.h
Go to the documentation of this file.
1#ifndef RB_DEBUG_H /*-*-C++-*-vi:se ft=cpp:*/
2#define RB_DEBUG_H 1
13#include "ruby/internal/attr/deprecated.h"
14#include "ruby/internal/attr/nonnull.h"
15#include "ruby/internal/attr/returns_nonnull.h"
16#include "ruby/internal/dllexport.h"
17#include "ruby/internal/event.h"
18#include "ruby/internal/value.h"
19
20 RBIMPL_SYMBOL_EXPORT_BEGIN()
21
22/* Note: This file contains experimental APIs. */
23/* APIs can be replaced at Ruby 2.0.1 or later */
24
25
30
31 RBIMPL_ATTR_NONNULL((3))
52int rb_profile_frames(int start, int limit, VALUE *buff, int *lines);
53
71int rb_profile_thread_frames(VALUE thread, int start, int limit, VALUE *buff, int *lines);
72
80 VALUE rb_profile_frame_path(VALUE frame);
81
93 VALUE rb_profile_frame_absolute_path(VALUE frame);
94
106 VALUE rb_profile_frame_label(VALUE frame);
107
132 VALUE rb_profile_frame_base_label(VALUE frame);
133
149 VALUE rb_profile_frame_full_label(VALUE frame);
150
159 VALUE rb_profile_frame_first_lineno(VALUE frame);
160
168 VALUE rb_profile_frame_classpath(VALUE frame);
169
177 VALUE rb_profile_frame_singleton_method_p(VALUE frame);
178
186 VALUE rb_profile_frame_method_name(VALUE frame);
187
196 VALUE rb_profile_frame_qualified_method_name(VALUE frame);
197
199
205
207typedef struct rb_debug_inspector_struct rb_debug_inspector_t;
208
218typedef VALUE (*rb_debug_inspector_func_t)(const rb_debug_inspector_t *dc, void *data);
219
227 VALUE rb_debug_inspector_open(rb_debug_inspector_func_t func, void *data);
228
238 VALUE rb_debug_inspector_backtrace_locations(const rb_debug_inspector_t *dc);
239
248 VALUE rb_debug_inspector_frame_self_get(const rb_debug_inspector_t *dc, long index);
249
258 VALUE rb_debug_inspector_frame_class_get(const rb_debug_inspector_t *dc, long index);
259
268 VALUE rb_debug_inspector_frame_binding_get(const rb_debug_inspector_t *dc, long index);
269
281 VALUE rb_debug_inspector_frame_iseq_get(const rb_debug_inspector_t *dc, long index);
282
294 VALUE rb_debug_inspector_frame_depth(const rb_debug_inspector_t *dc, long index);
295
296// A macro to recognize `rb_debug_inspector_frame_depth()` is available or not
297#define RB_DEBUG_INSPECTOR_FRAME_DEPTH(dc, index) rb_debug_inspector_frame_depth(dc, index)
298
304 VALUE rb_debug_inspector_current_depth(void);
305
307
313
314/* duplicated def of include/ruby/ruby.h */
315#include "ruby/internal/event.h"
316
328int rb_remove_event_hook_with_data(rb_event_hook_func_t func, VALUE data);
329
340void rb_thread_add_event_hook(VALUE thval, rb_event_hook_func_t func, rb_event_flag_t events, VALUE data);
341
355int rb_thread_remove_event_hook(VALUE thval, rb_event_hook_func_t func);
356
371int rb_thread_remove_event_hook_with_data(VALUE thval, rb_event_hook_func_t func, VALUE data);
372
374
380
423 VALUE rb_tracepoint_new(VALUE target_thread_not_supported_yet, rb_event_flag_t events, void (*func)(VALUE, void *), void *data);
424
435 VALUE rb_tracepoint_enable(VALUE tpval);
436
444 VALUE rb_tracepoint_disable(VALUE tpval);
445
453 VALUE rb_tracepoint_enabled_p(VALUE tpval);
454
465 typedef struct rb_trace_arg_struct rb_trace_arg_t;
466
467 RBIMPL_ATTR_RETURNS_NONNULL()
480 rb_trace_arg_t *rb_tracearg_from_tracepoint(VALUE tpval);
481
482 RBIMPL_ATTR_NONNULL((1))
489 rb_event_flag_t rb_tracearg_event_flag(rb_trace_arg_t *trace_arg);
490
491 RBIMPL_ATTR_NONNULL((1))
499 VALUE rb_tracearg_event(rb_trace_arg_t *trace_arg);
500
501 RBIMPL_ATTR_NONNULL((1))
509 VALUE rb_tracearg_lineno(rb_trace_arg_t *trace_arg);
510
511 RBIMPL_ATTR_NONNULL((1))
519 VALUE rb_tracearg_path(rb_trace_arg_t *trace_arg);
520
521 RBIMPL_ATTR_NONNULL((1))
531 VALUE rb_tracearg_parameters(rb_trace_arg_t *trace_arg);
532
533 RBIMPL_ATTR_NONNULL((1))
541 VALUE rb_tracearg_method_id(rb_trace_arg_t *trace_arg);
542
543 RBIMPL_ATTR_NONNULL((1))
552 VALUE rb_tracearg_callee_id(rb_trace_arg_t *trace_arg);
553
554 RBIMPL_ATTR_NONNULL((1))
564 VALUE rb_tracearg_defined_class(rb_trace_arg_t *trace_arg);
565
566 RBIMPL_ATTR_NONNULL((1))
579 VALUE rb_tracearg_binding(rb_trace_arg_t *trace_arg);
580
581 RBIMPL_ATTR_NONNULL((1))
588 VALUE rb_tracearg_self(rb_trace_arg_t *trace_arg);
589
590 RBIMPL_ATTR_NONNULL((1))
598 VALUE rb_tracearg_return_value(rb_trace_arg_t *trace_arg);
599
600 RBIMPL_ATTR_NONNULL((1))
608 VALUE rb_tracearg_raised_exception(rb_trace_arg_t *trace_arg);
609
610 RBIMPL_ATTR_NONNULL((1))
621 VALUE rb_tracearg_eval_script(rb_trace_arg_t *trace_arg);
622
623 RBIMPL_ATTR_NONNULL((1))
634 VALUE rb_tracearg_instruction_sequence(rb_trace_arg_t *trace_arg);
635
636 RBIMPL_ATTR_NONNULL((1))
644 VALUE rb_tracearg_object(rb_trace_arg_t *trace_arg);
645
646
648
654
655/*
656 * Postponed Job API
657 *
658 * This API is designed to be called from contexts where it is not safe to run Ruby
659 * code (e.g. because they do not hold the GVL or because GC is in progress), and
660 * defer a callback to run in a context where it _is_ safe. The primary intended
661 * users of this API is for sampling profilers like the "stackprof" gem; these work
662 * by scheduling the periodic delivery of a SIGPROF signal, and inside the C-level
663 * signal handler, deferring a job to collect a Ruby backtrace when it is next safe
664 * to do so.
665 *
666 * Ruby maintains a small, fixed-size postponed job table. An extension using this
667 * API should first call `rb_postponed_job_preregister` to register a callback
668 * function in this table and obtain a handle of type `rb_postponed_job_handle_t`
669 * to it. Subsequently, the callback can be triggered by calling
670 * `rb_postponed_job_trigger` with that handle, or the `data` associated with the
671 * callback function can be changed by calling `rb_postponed_job_preregister` again.
672 *
673 * Because the postponed job table is quite small (it only has 32 entries on most
674 * common systems), extensions should generally only preregister one or two `func`
675 * values.
676 *
677 * Historically, this API provided two functions `rb_postponed_job_register` and
678 * `rb_postponed_job_register_one`, which claimed to be fully async-signal-safe and
679 * would call back the provided `func` and `data` at an appropriate time. However,
680 * these functions were subject to race conditions which could cause crashes when
681 * racing with Ruby's internal use of them. These two functions are still present,
682 * but are marked as deprecated and have slightly changed semantics:
683 *
684 * * rb_postponed_job_register now works like rb_postponed_job_register_one i.e.
685 * `func` will only be executed at most one time each time Ruby checks for
686 * interrupts, no matter how many times it is registered
687 * * They are also called with the last `data` to be registered, not the first
688 * (which is how rb_postponed_job_register_one previously worked)
689 */
690
691
697typedef void (*rb_postponed_job_func_t)(void *arg);
698
703typedef unsigned int rb_postponed_job_handle_t;
704#define POSTPONED_JOB_HANDLE_INVALID ((rb_postponed_job_handle_t)UINT_MAX)
705
739 rb_postponed_job_handle_t rb_postponed_job_preregister(unsigned int flags, rb_postponed_job_func_t func, void *data);
740
755void rb_postponed_job_trigger(rb_postponed_job_handle_t h);
756
792 RBIMPL_ATTR_DEPRECATED(("use rb_postponed_job_preregister and rb_postponed_job_trigger"))
793int rb_postponed_job_register(unsigned int flags, rb_postponed_job_func_t func, void *data);
794
807 RBIMPL_ATTR_DEPRECATED(("use rb_postponed_job_preregister and rb_postponed_job_trigger"))
808int rb_postponed_job_register_one(unsigned int flags, rb_postponed_job_func_t func, void *data);
809
811
818
819/* undocumented advanced tracing APIs */
820
821typedef enum {
822 RUBY_EVENT_HOOK_FLAG_SAFE = 0x01,
823 RUBY_EVENT_HOOK_FLAG_DELETED = 0x02,
824 RUBY_EVENT_HOOK_FLAG_RAW_ARG = 0x04
825} rb_event_hook_flag_t;
826
827void rb_add_event_hook2(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data, rb_event_hook_flag_t hook_flag);
828void rb_thread_add_event_hook2(VALUE thval, rb_event_hook_func_t func, rb_event_flag_t events, VALUE data, rb_event_hook_flag_t hook_flag);
829
831
832 RBIMPL_SYMBOL_EXPORT_END()
833
834#endif /* RUBY_DEBUG_H */
rb_profile_frames
int rb_profile_frames(int start, int limit, VALUE *buff, int *lines)
Queries mysterious "frame"s of the given range.
Definition vm_backtrace.c:1805
rb_postponed_job_handle_t
unsigned int rb_postponed_job_handle_t
The type of a handle returned from rb_postponed_job_preregister and passed to rb_postponed_job_trigge...
Definition debug.h:703
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.
Definition vm_backtrace.c:2004
rb_debug_inspector_t
struct rb_debug_inspector_struct rb_debug_inspector_t
Opaque struct representing a debug inspector.
Definition debug.h:207
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.
Definition vm_trace.c:1096
rb_tracearg_parameters
VALUE rb_tracearg_parameters(rb_trace_arg_t *trace_arg)
Queries the parameters passed on a call or return event.
Definition vm_trace.c:1031
rb_tracearg_instruction_sequence
VALUE rb_tracearg_instruction_sequence(rb_trace_arg_t *trace_arg)
Queries the compiled instruction sequence on a 'script_compiled' event.
Definition vm_trace.c:1175
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.
Definition vm_backtrace.c:1699
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:1952
rb_debug_inspector_current_depth
VALUE rb_debug_inspector_current_depth(void)
Return current frame depth.
Definition vm_backtrace.c:1715
rb_tracepoint_enabled_p
VALUE rb_tracepoint_enabled_p(VALUE tpval)
Queries if the passed TracePoint is up and running.
Definition vm_trace.c:1616
rb_tracearg_object
VALUE rb_tracearg_object(rb_trace_arg_t *trace_arg)
Queries the allocated/deallocated object that the trace represents.
Definition vm_trace.c:1202
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().
Definition vm_trace.c:1082
rb_profile_frame_method_name
VALUE rb_profile_frame_method_name(VALUE frame)
Queries the name of the method of the passed frame.
Definition vm_backtrace.c:1964
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.
Definition vm_trace.c:1089
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:1646
rb_trace_arg_t
struct rb_trace_arg_struct rb_trace_arg_t
Type that represents a specific trace event.
Definition debug.h:465
rb_tracearg_raised_exception
VALUE rb_tracearg_raised_exception(rb_trace_arg_t *trace_arg)
Queries the raised exception that the trace represents.
Definition vm_trace.c:1136
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:1708
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.
Definition vm_trace.c:266
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:1918
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...
Definition vm_backtrace.c:1996
rb_profile_frame_label
VALUE rb_profile_frame_label(VALUE frame)
Queries human-readable "label" string.
Definition vm_backtrace.c:1899
rb_tracepoint_disable
VALUE rb_tracepoint_disable(VALUE tpval)
Stops (disables) an already running instance of TracePoint.
Definition vm_trace.c:1472
rb_tracearg_self
VALUE rb_tracearg_self(rb_trace_arg_t *trace_arg)
Queries the receiver of the point trace is at.
Definition vm_trace.c:1115
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.
Definition vm_trace.c:415
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.
Definition vm_backtrace.c:1956
rb_debug_inspector_backtrace_locations
VALUE rb_debug_inspector_backtrace_locations(const rb_debug_inspector_t *dc)
Queries the backtrace object of the context.
Definition vm_backtrace.c:1722
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.
Definition vm_backtrace.c:1884
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.
Definition vm_trace.c:1982
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.
Definition vm_backtrace.c:1633
rb_tracearg_return_value
VALUE rb_tracearg_return_value(rb_trace_arg_t *trace_arg)
Queries the return value that the trace represents.
Definition vm_trace.c:1121
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.
Definition vm_trace.c:977
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.
Definition vm_backtrace.c:1678
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.
Definition vm_trace.c:1003
rb_tracearg_eval_script
VALUE rb_tracearg_eval_script(rb_trace_arg_t *trace_arg)
Queries the compiled source code of the 'script_compiled' event.
Definition vm_trace.c:1151
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.
Definition vm_trace.c:421
rb_tracepoint_enable
VALUE rb_tracepoint_enable(VALUE tpval)
Starts (enables) trace(s) defined by the passed object.
Definition vm_trace.c:1309
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.
Definition vm_backtrace.c:1692
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.
Definition vm_trace.c:1976
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.
Definition vm_trace.c:1075
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.
Definition vm_backtrace.c:1685
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.
Definition vm_trace.c:433
rb_profile_frame_classpath
VALUE rb_profile_frame_classpath(VALUE frame)
Queries the class path of the method that the passed frame represents.
Definition vm_backtrace.c:1935
rb_tracearg_from_tracepoint
rb_trace_arg_t * rb_tracearg_from_tracepoint(VALUE tpval)
Queries the current event of the passed tracepoint.
Definition vm_trace.c:971
rb_profile_frame_path
VALUE rb_profile_frame_path(VALUE frame)
Queries the path of the passed backtrace.
Definition vm_backtrace.c:1852
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.
Definition vm_backtrace.c:1913
rb_tracearg_lineno
VALUE rb_tracearg_lineno(rb_trace_arg_t *trace_arg)
Queries the line of the point where the trace is at.
Definition vm_trace.c:997
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.
Definition vm_backtrace.c:1819
rb_postponed_job_func_t
void(* rb_postponed_job_func_t)(void *arg)
Type of postponed jobs.
Definition debug.h:697
rb_debug_inspector_func_t
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().
Definition debug.h:218
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.
Definition vm_backtrace.c:1906
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.
Definition vm_trace.c:983
deprecated.h
Defines RBIMPL_ATTR_DEPRECATED.
RBIMPL_ATTR_DEPRECATED
#define RBIMPL_ATTR_DEPRECATED(msg)
Wraps (or simulates) [[deprecated]].
Definition deprecated.h:64
dllexport.h
Tweaking visibility of C variables/functions.
RBIMPL_SYMBOL_EXPORT_END
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition dllexport.h:74
RBIMPL_SYMBOL_EXPORT_BEGIN
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:65
event.h
Debugging and tracing APIs.
rb_event_hook_func_t
void(* rb_event_hook_func_t)(rb_event_flag_t evflag, VALUE data, VALUE self, ID mid, VALUE klass)
Type of event hooks.
Definition event.h:120
rb_event_flag_t
uint32_t rb_event_flag_t
Represents event(s).
Definition event.h:108
nonnull.h
Defines RBIMPL_ATTR_NONNULL.
RBIMPL_ATTR_NONNULL
#define RBIMPL_ATTR_NONNULL(list)
Wraps (or simulates) __attribute__((nonnull)).
Definition nonnull.h:30
returns_nonnull.h
Defines RBIMPL_ATTR_RETURNS_NONNULL.
RBIMPL_ATTR_RETURNS_NONNULL
#define RBIMPL_ATTR_RETURNS_NONNULL()
Wraps (or simulates) __attribute__((returns_nonnull)).
Definition returns_nonnull.h:34
rb_debug_inspector_struct
Definition vm_backtrace.c:1493
rb_trace_arg_struct
Definition vm_core.h:2271
value.h
Defines VALUE and ID.
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40