debug.h

Go to the documentation of this file.

#ifndef RB_DEBUG_H                                   /*-*-C++-*-vi:se ft=cpp:*/
#define RB_DEBUG_H 1
#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"
 
RBIMPL_SYMBOL_EXPORT_BEGIN()
 
/* Note: This file contains experimental APIs. */
/* APIs can be replaced at Ruby 2.0.1 or later */
 
 
RBIMPL_ATTR_NONNULL((3))
int rb_profile_frames(int start, int limit, VALUE *buff, int *lines);
 
int rb_profile_thread_frames(VALUE thread, int start, int limit, VALUE *buff, int *lines);
 
VALUE rb_profile_frame_path(VALUE frame);
 
VALUE rb_profile_frame_absolute_path(VALUE frame);
 
VALUE rb_profile_frame_label(VALUE frame);
 
VALUE rb_profile_frame_base_label(VALUE frame);
 
VALUE rb_profile_frame_full_label(VALUE frame);
 
VALUE rb_profile_frame_first_lineno(VALUE frame);
 
VALUE rb_profile_frame_classpath(VALUE frame);
 
VALUE rb_profile_frame_singleton_method_p(VALUE frame);
 
VALUE rb_profile_frame_method_name(VALUE frame);
 
VALUE rb_profile_frame_qualified_method_name(VALUE frame);
 
typedef struct rb_debug_inspector_struct rb_debug_inspector_t;
 
typedef VALUE (*rb_debug_inspector_func_t)(const rb_debug_inspector_t *dc, void *data);
 
VALUE rb_debug_inspector_open(rb_debug_inspector_func_t func, void *data);
 
VALUE rb_debug_inspector_backtrace_locations(const rb_debug_inspector_t *dc);
 
VALUE rb_debug_inspector_frame_self_get(const rb_debug_inspector_t *dc, long index);
 
VALUE rb_debug_inspector_frame_class_get(const rb_debug_inspector_t *dc, long index);
 
VALUE rb_debug_inspector_frame_binding_get(const rb_debug_inspector_t *dc, long index);
 
VALUE rb_debug_inspector_frame_iseq_get(const rb_debug_inspector_t *dc, long index);
 
VALUE rb_debug_inspector_frame_depth(const rb_debug_inspector_t *dc, long index);
 
// A macro to recognize `rb_debug_inspector_frame_depth()` is available or not
#define RB_DEBUG_INSPECTOR_FRAME_DEPTH(dc, index) rb_debug_inspector_frame_depth(dc, index)
 
VALUE rb_debug_inspector_current_depth(void);
 
/* duplicated def of include/ruby/ruby.h */
#include "ruby/internal/event.h"
 
int rb_remove_event_hook_with_data(rb_event_hook_func_t func, VALUE data);
 
void rb_thread_add_event_hook(VALUE thval, rb_event_hook_func_t func, rb_event_flag_t events, VALUE data);
 
int rb_thread_remove_event_hook(VALUE thval, rb_event_hook_func_t func);
 
int rb_thread_remove_event_hook_with_data(VALUE thval, rb_event_hook_func_t func, VALUE data);
 
VALUE rb_tracepoint_new(VALUE target_thread_not_supported_yet, rb_event_flag_t events, void (*func)(VALUE, void *), void *data);
 
VALUE rb_tracepoint_enable(VALUE tpval);
 
VALUE rb_tracepoint_disable(VALUE tpval);
 
VALUE rb_tracepoint_enabled_p(VALUE tpval);
 
typedef struct rb_trace_arg_struct rb_trace_arg_t;
 
RBIMPL_ATTR_RETURNS_NONNULL()
rb_trace_arg_t *rb_tracearg_from_tracepoint(VALUE tpval);
 
RBIMPL_ATTR_NONNULL(())
rb_event_flag_t rb_tracearg_event_flag(rb_trace_arg_t *trace_arg);
 
RBIMPL_ATTR_NONNULL(())
VALUE rb_tracearg_event(rb_trace_arg_t *trace_arg);
 
RBIMPL_ATTR_NONNULL(())
VALUE rb_tracearg_lineno(rb_trace_arg_t *trace_arg);
 
RBIMPL_ATTR_NONNULL(())
VALUE rb_tracearg_path(rb_trace_arg_t *trace_arg);
 
RBIMPL_ATTR_NONNULL(())
VALUE rb_tracearg_method_id(rb_trace_arg_t *trace_arg);
 
RBIMPL_ATTR_NONNULL(())
VALUE rb_tracearg_callee_id(rb_trace_arg_t *trace_arg);
 
RBIMPL_ATTR_NONNULL(())
VALUE rb_tracearg_defined_class(rb_trace_arg_t *trace_arg);
 
RBIMPL_ATTR_NONNULL(())
VALUE rb_tracearg_binding(rb_trace_arg_t *trace_arg);
 
RBIMPL_ATTR_NONNULL(())
VALUE rb_tracearg_self(rb_trace_arg_t *trace_arg);
 
RBIMPL_ATTR_NONNULL(())
VALUE rb_tracearg_return_value(rb_trace_arg_t *trace_arg);
 
RBIMPL_ATTR_NONNULL(())
VALUE rb_tracearg_raised_exception(rb_trace_arg_t *trace_arg);
 
RBIMPL_ATTR_NONNULL(())
VALUE rb_tracearg_object(rb_trace_arg_t *trace_arg);
 
 
/*
 * Postponed Job API
 *
 * This API is designed to be called from contexts where it is not safe to run Ruby
 * code (e.g. because they do not hold the GVL or because GC is in progress), and
 * defer a callback to run in a context where it _is_ safe. The primary intended
 * users of this API is for sampling profilers like the "stackprof" gem; these work
 * by scheduling the periodic delivery of a SIGPROF signal, and inside the C-level
 * signal handler, deferring a job to collect a Ruby backtrace when it is next safe
 * to do so.
 *
 * Ruby maintains a small, fixed-size postponed job table. An extension using this
 * API should first call `rb_postponed_job_preregister` to register a callback
 * function in this table and obtain a handle of type `rb_postponed_job_handle_t`
 * to it. Subsequently, the callback can be triggered  by calling
 * `rb_postponed_job_trigger` with that handle, or the `data` associated with the
 * callback function can be changed by calling `rb_postponed_job_preregister` again.
 *
 * Because the postponed job table is quite small (it only has 32 entries on most
 * common systems), extensions should generally only preregister one or two `func`
 * values.
 *
 * Historically, this API provided two functions `rb_postponed_job_register` and
 * `rb_postponed_job_register_one`, which claimed to be fully async-signal-safe and
 * would call back the provided `func` and `data` at an appropriate time. However,
 * these functions were subject to race conditions which could cause crashes when
 * racing with Ruby's internal use of them. These two functions are still present,
 * but are marked as deprecated and have slightly changed semantics:
 *
 * * rb_postponed_job_register now works like rb_postponed_job_register_one i.e.
 *   `func` will only be executed at most one time each time Ruby checks for
 *   interrupts, no matter how many times it is registered
 * * They are also called with the last `data` to be registered, not the first
 *   (which is how rb_postponed_job_register_one previously worked)
 */
 
 
typedef void (*rb_postponed_job_func_t)(void *arg);
 
typedef unsigned int rb_postponed_job_handle_t;
#define POSTPONED_JOB_HANDLE_INVALID ((rb_postponed_job_handle_t)UINT_MAX)
 
rb_postponed_job_handle_t rb_postponed_job_preregister(unsigned int flags, rb_postponed_job_func_t func, void *data);
 
void rb_postponed_job_trigger(rb_postponed_job_handle_t h);
 
 RBIMPL_ATTR_DEPRECATED(("use rb_postponed_job_preregister and rb_postponed_job_trigger"))
int rb_postponed_job_register(unsigned int flags, rb_postponed_job_func_t func, void *data);
 
 RBIMPL_ATTR_DEPRECATED(("use rb_postponed_job_preregister and rb_postponed_job_trigger"))
int rb_postponed_job_register_one(unsigned int flags, rb_postponed_job_func_t func, void *data);
 
/* undocumented advanced tracing APIs */
 
typedef enum {
    RUBY_EVENT_HOOK_FLAG_SAFE    = 0x01,
    RUBY_EVENT_HOOK_FLAG_DELETED = 0x02,
    RUBY_EVENT_HOOK_FLAG_RAW_ARG = 0x04
} rb_event_hook_flag_t;
 
void rb_add_event_hook2(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data, rb_event_hook_flag_t hook_flag);
void 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);
 
RBIMPL_SYMBOL_EXPORT_END()
 
#endif /* RUBY_DEBUG_H */