Ruby: include/ruby/debug.h Source File

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

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/nonnull.h"
14#include "ruby/internal/attr/returns_nonnull.h"
15#include "ruby/internal/dllexport.h"
16#include "ruby/internal/event.h"
17#include "ruby/internal/value.h"
18
19 RBIMPL_SYMBOL_EXPORT_BEGIN()
20
21/* Note: This file contains experimental APIs. */
22/* APIs can be replaced at Ruby 2.0.1 or later */
23
24
30 RBIMPL_ATTR_NONNULL((3))
51int rb_profile_frames(int start, int limit, VALUE *buff, int *lines);
52
60 VALUE rb_profile_frame_path(VALUE frame);
61
73 VALUE rb_profile_frame_absolute_path(VALUE frame);
74
86 VALUE rb_profile_frame_label(VALUE frame);
87
112 VALUE rb_profile_frame_base_label(VALUE frame);
113
129 VALUE rb_profile_frame_full_label(VALUE frame);
130
139 VALUE rb_profile_frame_first_lineno(VALUE frame);
140
148 VALUE rb_profile_frame_classpath(VALUE frame);
149
157 VALUE rb_profile_frame_singleton_method_p(VALUE frame);
158
166 VALUE rb_profile_frame_method_name(VALUE frame);
167
176 VALUE rb_profile_frame_qualified_method_name(VALUE frame);
177
187typedef struct rb_debug_inspector_struct rb_debug_inspector_t;
188
198typedef VALUE (*rb_debug_inspector_func_t)(const rb_debug_inspector_t *dc, void *data);
199
207 VALUE rb_debug_inspector_open(rb_debug_inspector_func_t func, void *data);
208
218 VALUE rb_debug_inspector_backtrace_locations(const rb_debug_inspector_t *dc);
219
228 VALUE rb_debug_inspector_frame_self_get(const rb_debug_inspector_t *dc, long index);
229
238 VALUE rb_debug_inspector_frame_class_get(const rb_debug_inspector_t *dc, long index);
239
248 VALUE rb_debug_inspector_frame_binding_get(const rb_debug_inspector_t *dc, long index);
249
261 VALUE rb_debug_inspector_frame_iseq_get(const rb_debug_inspector_t *dc, long index);
262
274 VALUE rb_debug_inspector_frame_depth(const rb_debug_inspector_t *dc, long index);
275
276// A macro to recognize `rb_debug_inspector_frame_depth()` is available or not
277#define RB_DEBUG_INSPECTOR_FRAME_DEPTH(dc, index) rb_debug_inspector_frame_depth(dc, index)
278
284 VALUE rb_debug_inspector_current_depth(void);
285
294/* duplicated def of include/ruby/ruby.h */
295#include "ruby/internal/event.h"
296
308int rb_remove_event_hook_with_data(rb_event_hook_func_t func, VALUE data);
309
320void rb_thread_add_event_hook(VALUE thval, rb_event_hook_func_t func, rb_event_flag_t events, VALUE data);
321
335int rb_thread_remove_event_hook(VALUE thval, rb_event_hook_func_t func);
336
351int rb_thread_remove_event_hook_with_data(VALUE thval, rb_event_hook_func_t func, VALUE data);
352
403 VALUE rb_tracepoint_new(VALUE target_thread_not_supported_yet, rb_event_flag_t events, void (*func)(VALUE, void *), void *data);
404
415 VALUE rb_tracepoint_enable(VALUE tpval);
416
424 VALUE rb_tracepoint_disable(VALUE tpval);
425
433 VALUE rb_tracepoint_enabled_p(VALUE tpval);
434
445 typedef struct rb_trace_arg_struct rb_trace_arg_t;
446
447 RBIMPL_ATTR_RETURNS_NONNULL()
460 rb_trace_arg_t *rb_tracearg_from_tracepoint(VALUE tpval);
461
462 RBIMPL_ATTR_NONNULL(())
469 rb_event_flag_t rb_tracearg_event_flag(rb_trace_arg_t *trace_arg);
470
471 RBIMPL_ATTR_NONNULL(())
479 VALUE rb_tracearg_event(rb_trace_arg_t *trace_arg);
480
481 RBIMPL_ATTR_NONNULL(())
489 VALUE rb_tracearg_lineno(rb_trace_arg_t *trace_arg);
490
491 RBIMPL_ATTR_NONNULL(())
499 VALUE rb_tracearg_path(rb_trace_arg_t *trace_arg);
500
501 RBIMPL_ATTR_NONNULL(())
509 VALUE rb_tracearg_method_id(rb_trace_arg_t *trace_arg);
510
511 RBIMPL_ATTR_NONNULL(())
520 VALUE rb_tracearg_callee_id(rb_trace_arg_t *trace_arg);
521
522 RBIMPL_ATTR_NONNULL(())
532 VALUE rb_tracearg_defined_class(rb_trace_arg_t *trace_arg);
533
534 RBIMPL_ATTR_NONNULL(())
547 VALUE rb_tracearg_binding(rb_trace_arg_t *trace_arg);
548
549 RBIMPL_ATTR_NONNULL(())
556 VALUE rb_tracearg_self(rb_trace_arg_t *trace_arg);
557
558 RBIMPL_ATTR_NONNULL(())
566 VALUE rb_tracearg_return_value(rb_trace_arg_t *trace_arg);
567
568 RBIMPL_ATTR_NONNULL(())
576 VALUE rb_tracearg_raised_exception(rb_trace_arg_t *trace_arg);
577
578 RBIMPL_ATTR_NONNULL(())
586 VALUE rb_tracearg_object(rb_trace_arg_t *trace_arg);
587
588
597/*
598 * Postponed Job API
599 * rb_postponed_job_register and rb_postponed_job_register_one are
600 * async-signal-safe and used via SIGPROF by the "stackprof" RubyGem
601 */
602
608typedef void (*rb_postponed_job_func_t)(void *arg);
609
628int rb_postponed_job_register(unsigned int flags, rb_postponed_job_func_t func, void *data);
629
641int rb_postponed_job_register_one(unsigned int flags, rb_postponed_job_func_t func, void *data);
642
652/* undocumented advanced tracing APIs */
653
654typedef enum {
655 RUBY_EVENT_HOOK_FLAG_SAFE = 0x01,
656 RUBY_EVENT_HOOK_FLAG_DELETED = 0x02,
657 RUBY_EVENT_HOOK_FLAG_RAW_ARG = 0x04
658} rb_event_hook_flag_t;
659
660void rb_add_event_hook2(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data, rb_event_hook_flag_t hook_flag);
661void 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);
662
665 RBIMPL_SYMBOL_EXPORT_END()
666
667#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:1576
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:1808
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:956
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:1547
rb_debug_inspector_current_depth
VALUE rb_debug_inspector_current_depth(void)
Return current frmae depth.
Definition vm_backtrace.c:1563
rb_tracepoint_enabled_p
VALUE rb_tracepoint_enabled_p(VALUE tpval)
Queries if the passed TracePoint is up and running.
Definition vm_trace.c:1410
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:1062
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:942
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:1768
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:949
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
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:996
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
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:179
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:1800
rb_profile_frame_label
VALUE rb_profile_frame_label(VALUE frame)
Queries human-readable "label" string.
Definition vm_backtrace.c:1703
rb_tracepoint_disable
VALUE rb_tracepoint_disable(VALUE tpval)
Stops (disables) an already running instance of TracePoint.
Definition vm_trace.c:1287
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:975
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:281
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:1760
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:1570
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:1688
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 registrati...
Definition vm_trace.c:1704
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:1485
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:981
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:841
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:1526
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:867
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:287
rb_tracepoint_enable
VALUE rb_tracepoint_enable(VALUE tpval)
Starts (enables) trace(s) defined by the passed object.
Definition vm_trace.c:1169
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:1540
rb_postponed_job_register
int rb_postponed_job_register(unsigned int flags, rb_postponed_job_func_t func, void *data)
Registers a postponed job.
Definition vm_trace.c:1685
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:935
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:1533
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:299
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:1739
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:835
rb_profile_frame_path
VALUE rb_profile_frame_path(VALUE frame)
Queries the path of the passed backtrace.
Definition vm_backtrace.c:1656
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:1717
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:861
rb_postponed_job_func_t
void(* rb_postponed_job_func_t)(void *arg)
Type of postponed jobs.
Definition debug.h:608
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:198
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:1710
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:847
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:106
RBIMPL_SYMBOL_EXPORT_BEGIN
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:97
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:115
rb_event_flag_t
uint32_t rb_event_flag_t
Represents event(s).
Definition event.h:103
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:1364
rb_trace_arg_struct
Definition vm_core.h:1995
value.h
Defines VALUE and ID.
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40