(892c46283a5ea4179500d951c9d4866c0051f27b)

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

int	rb_profile_thread_frames (VALUE thread, int start, int limit, VALUE buff, int lines)
	Queries mysterious "frame"s of the given range. More...

VALUE	rb_profile_frame_path (VALUE frame)
	Queries the path of the passed backtrace. More...

VALUE	rb_profile_frame_absolute_path (VALUE frame)
	Identical to rb_profile_frame_path(), except it tries to expand the returning path. More...

VALUE	rb_profile_frame_label (VALUE frame)
	Queries human-readable "label" string. More...

VALUE	rb_profile_frame_base_label (VALUE frame)
	Identical to rb_profile_frame_label(), except it does not "qualify" the result. More...

VALUE	rb_profile_frame_full_label (VALUE frame)
	Identical to rb_profile_frame_label(), except it returns a qualified result. More...

VALUE	rb_profile_frame_first_lineno (VALUE frame)
	Queries the first line of the method of the passed frame pointer. More...

VALUE	rb_profile_frame_classpath (VALUE frame)
	Queries the class path of the method that the passed frame represents. More...

VALUE	rb_profile_frame_singleton_method_p (VALUE frame)
	Queries if the method of the passed frame is a singleton class. More...

VALUE	rb_profile_frame_method_name (VALUE frame)
	Queries the name of the method of the passed frame. More...

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

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

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

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

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

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

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

VALUE	rb_debug_inspector_open (rb_debug_inspector_func_t func, void *data)
	Prepares, executes, then cleans up a debug session. More...

VALUE	rb_debug_inspector_backtrace_locations (const rb_debug_inspector_t *dc)
	Queries the backtrace object of the context. More...

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

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

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

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

VALUE	rb_debug_inspector_frame_depth (const rb_debug_inspector_t *dc, long index)
	Queries the depth of the passed context's upper frame. More...

VALUE	rb_debug_inspector_current_depth (void)
	Return current frmae depth. More...

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

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

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

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

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

int	rb_postponed_job_register_one (unsigned int flags, rb_postponed_job_func_t func, void *data)
	Identical to `rb_postponed_job_register` More...

TracePoint APIs
typedef struct rb_trace_arg_struct	rb_trace_arg_t
	Type that represents a specific trace event. More...

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

VALUE	rb_tracepoint_enable (VALUE tpval)
	Starts (enables) trace(s) defined by the passed object. More...

VALUE	rb_tracepoint_disable (VALUE tpval)
	Stops (disables) an already running instance of TracePoint. More...

VALUE	rb_tracepoint_enabled_p (VALUE tpval)
	Queries if the passed TracePoint is up and running. More...

rb_trace_arg_t *	rb_tracearg_from_tracepoint (VALUE tpval)
	Queries the current event of the passed tracepoint. More...

rb_event_flag_t	rb_tracearg_event_flag (rb_trace_arg_t *trace_arg)
	Queries the event of the passed trace. More...

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

VALUE	rb_tracearg_lineno (rb_trace_arg_t *trace_arg)
	Queries the line of the point where the trace is at. More...

VALUE	rb_tracearg_path (rb_trace_arg_t *trace_arg)
	Queries the file name of the point where the trace is at. More...

VALUE	rb_tracearg_method_id (rb_trace_arg_t *trace_arg)
	Queries the method name of the point where the trace is at. More...

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

VALUE	rb_tracearg_defined_class (rb_trace_arg_t *trace_arg)
	Queries the class that defines the method that the passed trace is at. More...

VALUE	rb_tracearg_binding (rb_trace_arg_t *trace_arg)
	Creates a binding object of the point where the trace is at. More...

VALUE	rb_tracearg_self (rb_trace_arg_t *trace_arg)
	Queries the receiver of the point trace is at. More...

VALUE	rb_tracearg_return_value (rb_trace_arg_t *trace_arg)
	Queries the return value that the trace represents. More...

VALUE	rb_tracearg_raised_exception (rb_trace_arg_t *trace_arg)
	Queries the raised exception that the trace represents. More...

VALUE	rb_tracearg_object (rb_trace_arg_t *trace_arg)
	Queries the allocated/deallocated object that the trace represents. More...

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.

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

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

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

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

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

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

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

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

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

◆ 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:1786

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:1752

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

◆ 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_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 981 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 967 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 974 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 868 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 862 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 856 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 882 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 960 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 1087 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 888 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 1021 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 1006 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 1000 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 1320 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 1194 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 1446 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:

VALUE tpval - the TracePoint object from which trace args can be extracted.

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

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

(892c46283a5ea4179500d951c9d4866c0051f27b)

Functions

Debug inspector APIs

Postponed Job API

TracePoint APIs

Detailed Description

Typedef Documentation

◆ rb_debug_inspector_func_t

◆ rb_debug_inspector_t

◆ rb_postponed_job_func_t

◆ rb_postponed_job_handle_t

◆ rb_trace_arg_t

Function Documentation

◆ rb_debug_inspector_backtrace_locations()

◆ rb_debug_inspector_current_depth()

◆ rb_debug_inspector_frame_binding_get()

◆ rb_debug_inspector_frame_class_get()

◆ rb_debug_inspector_frame_depth()

◆ rb_debug_inspector_frame_iseq_get()

◆ rb_debug_inspector_frame_self_get()

◆ rb_debug_inspector_open()

◆ rb_postponed_job_preregister()

◆ rb_postponed_job_register()

◆ rb_postponed_job_register_one()

◆ rb_postponed_job_trigger()

◆ rb_profile_frame_absolute_path()

◆ rb_profile_frame_base_label()

◆ rb_profile_frame_classpath()

◆ rb_profile_frame_first_lineno()

◆ rb_profile_frame_full_label()

◆ rb_profile_frame_label()

◆ rb_profile_frame_method_name()

◆ rb_profile_frame_path()

◆ rb_profile_frame_qualified_method_name()

◆ rb_profile_frame_singleton_method_p()

◆ rb_profile_frames()

◆ rb_profile_thread_frames()

◆ rb_remove_event_hook_with_data()

◆ rb_thread_add_event_hook()

◆ rb_thread_remove_event_hook()

◆ rb_thread_remove_event_hook_with_data()

◆ rb_tracearg_binding()

◆ rb_tracearg_callee_id()

◆ rb_tracearg_defined_class()

◆ rb_tracearg_event()

◆ rb_tracearg_event_flag()

◆ rb_tracearg_from_tracepoint()

◆ rb_tracearg_lineno()

◆ rb_tracearg_method_id()

◆ rb_tracearg_object()

◆ rb_tracearg_path()

◆ rb_tracearg_raised_exception()

◆ rb_tracearg_return_value()

◆ rb_tracearg_self()

◆ rb_tracepoint_disable()

◆ rb_tracepoint_enable()

◆ rb_tracepoint_enabled_p()

◆ rb_tracepoint_new()