(348a53415339076afc4a02fcd09f3ae36e9c4c61)

Debugging and tracing APIs. More...

#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"

Include dependency graph for event.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	RB_EVENT_HOOKS_HAVE_CALLBACK_DATA 1

Traditional set_trace_func events
#define	RUBY_EVENT_NONE 0x0000
	No events. More...

#define	RUBY_EVENT_LINE 0x0001
	Encountered a new line. More...

#define	RUBY_EVENT_CLASS 0x0002
	Encountered a new class. More...

#define	RUBY_EVENT_END 0x0004
	Encountered an end of a class clause. More...

#define	RUBY_EVENT_CALL 0x0008
	A method, written in Ruby, is called. More...

#define	RUBY_EVENT_RETURN 0x0010
	Encountered a `return` statement. More...

#define	RUBY_EVENT_C_CALL 0x0020
	A method, written in C, is called. More...

#define	RUBY_EVENT_C_RETURN 0x0040
	Return from a method, written in C. More...

#define	RUBY_EVENT_RAISE 0x0080
	Encountered a `raise` statement. More...

#define	RUBY_EVENT_ALL 0x00ff
	Bitmask of traditional events. More...

TracePoint extended events
#define	RUBY_EVENT_B_CALL 0x0100
	Encountered an `yield` statement. More...

#define	RUBY_EVENT_B_RETURN 0x0200
	Encountered a `next` statement. More...

#define	RUBY_EVENT_THREAD_BEGIN 0x0400
	Encountered a new thread. More...

#define	RUBY_EVENT_THREAD_END 0x0800
	Encountered an end of a thread. More...

#define	RUBY_EVENT_FIBER_SWITCH 0x1000
	Encountered a `Fiber#yield`. More...

#define	RUBY_EVENT_SCRIPT_COMPILED 0x2000
	Encountered an `eval`. More...

#define	RUBY_EVENT_RESCUE 0x4000
	Encountered a `rescue` statement. More...

#define	RUBY_EVENT_TRACEPOINT_ALL 0xffff
	Bitmask of extended events. More...

Special events
#define	RUBY_EVENT_RESERVED_FOR_INTERNAL_USE 0x030000
	Opaque bits. More...

Internal events
@shyouhei's understanding is that some of them are visible from extension libraries because of `ext/objspace`. But it seems that doesn't describe everything? The ultimate reason why they are here remains unclear.
#define	RUBY_INTERNAL_EVENT_SWITCH 0x040000
	Thread switched. More...

#define	RUBY_EVENT_SWITCH 0x040000
	Old name of RUBY_INTERNAL_EVENT_SWITCH. More...

#define	RUBY_INTERNAL_EVENT_NEWOBJ 0x100000
	Object allocated. More...

#define	RUBY_INTERNAL_EVENT_FREEOBJ 0x200000
	Object swept. More...

#define	RUBY_INTERNAL_EVENT_GC_START 0x400000
	GC started. More...

#define	RUBY_INTERNAL_EVENT_GC_END_MARK 0x800000
	GC ended mark phase. More...

#define	RUBY_INTERNAL_EVENT_GC_END_SWEEP 0x1000000
	GC ended sweep phase. More...

#define	RUBY_INTERNAL_EVENT_GC_ENTER 0x2000000
	`gc_enter()` is called. More...

#define	RUBY_INTERNAL_EVENT_GC_EXIT 0x4000000
	`gc_exit()` is called. More...

#define	RUBY_INTERNAL_EVENT_OBJSPACE_MASK 0x7f00000
	Bitmask of GC events. More...

#define	RUBY_INTERNAL_EVENT_MASK 0xffff0000
	Bitmask of internal events. More...

Typedefs
typedef uint32_t	rb_event_flag_t
	Represents event(s). More...

typedef void(*	rb_event_hook_func_t) (rb_event_flag_t evflag, VALUE data, VALUE self, ID mid, VALUE klass)
	Type of event hooks. More...

Functions
void	rb_add_event_hook (rb_event_hook_func_t func, rb_event_flag_t events, VALUE data)
	Registers an event hook function. More...

int	rb_remove_event_hook (rb_event_hook_func_t func)
	Removes the passed function from the list of event hooks. More...

Detailed Description

Debugging and tracing APIs.

Author: Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright: 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.

Warning: Symbols prefixed with either RBIMPL or rbimpl are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note: To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance __VA_ARGS__ is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file event.h.

Macro Definition Documentation

◆ RB_EVENT_HOOKS_HAVE_CALLBACK_DATA

#define RB_EVENT_HOOKS_HAVE_CALLBACK_DATA 1

Deprecated:: This macro once was a thing in the old days, but makes no sense any longer today.

Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 129 of file event.h.

◆ RUBY_EVENT_ALL

#define RUBY_EVENT_ALL 0x00ff

Bitmask of traditional events.

Definition at line 46 of file event.h.

◆ RUBY_EVENT_B_CALL

#define RUBY_EVENT_B_CALL 0x0100

Encountered an yield statement.

Definition at line 55 of file event.h.

◆ RUBY_EVENT_B_RETURN

#define RUBY_EVENT_B_RETURN 0x0200

Encountered a next statement.

Definition at line 56 of file event.h.

◆ RUBY_EVENT_C_CALL

#define RUBY_EVENT_C_CALL 0x0020

A method, written in C, is called.

Definition at line 43 of file event.h.

◆ RUBY_EVENT_C_RETURN

#define RUBY_EVENT_C_RETURN 0x0040

Return from a method, written in C.

Definition at line 44 of file event.h.

◆ RUBY_EVENT_CALL

#define RUBY_EVENT_CALL 0x0008

A method, written in Ruby, is called.

Definition at line 41 of file event.h.

◆ RUBY_EVENT_CLASS

#define RUBY_EVENT_CLASS 0x0002

Encountered a new class.

Definition at line 39 of file event.h.

◆ RUBY_EVENT_END

#define RUBY_EVENT_END 0x0004

Encountered an end of a class clause.

Definition at line 40 of file event.h.

◆ RUBY_EVENT_FIBER_SWITCH

#define RUBY_EVENT_FIBER_SWITCH 0x1000

Encountered a Fiber#yield.

Definition at line 59 of file event.h.

◆ RUBY_EVENT_LINE

#define RUBY_EVENT_LINE 0x0001

Encountered a new line.

Definition at line 38 of file event.h.

◆ RUBY_EVENT_NONE

#define RUBY_EVENT_NONE 0x0000

No events.

Definition at line 37 of file event.h.

◆ RUBY_EVENT_RAISE

#define RUBY_EVENT_RAISE 0x0080

Encountered a raise statement.

Definition at line 45 of file event.h.

◆ RUBY_EVENT_RESCUE

#define RUBY_EVENT_RESCUE 0x4000

Encountered a rescue statement.

Definition at line 61 of file event.h.

◆ RUBY_EVENT_RESERVED_FOR_INTERNAL_USE

#define RUBY_EVENT_RESERVED_FOR_INTERNAL_USE 0x030000

Opaque bits.

Definition at line 77 of file event.h.

◆ RUBY_EVENT_RETURN

#define RUBY_EVENT_RETURN 0x0010

Encountered a return statement.

Definition at line 42 of file event.h.

◆ RUBY_EVENT_SCRIPT_COMPILED

#define RUBY_EVENT_SCRIPT_COMPILED 0x2000

Encountered an eval.

Definition at line 60 of file event.h.

◆ RUBY_EVENT_THREAD_BEGIN

#define RUBY_EVENT_THREAD_BEGIN 0x0400

Encountered a new thread.

Definition at line 57 of file event.h.

◆ RUBY_EVENT_THREAD_END

#define RUBY_EVENT_THREAD_END 0x0800

Encountered an end of a thread.

Definition at line 58 of file event.h.

◆ RUBY_EVENT_TRACEPOINT_ALL

#define RUBY_EVENT_TRACEPOINT_ALL 0xffff

Bitmask of extended events.

Definition at line 62 of file event.h.

◆ RUBY_INTERNAL_EVENT_FREEOBJ

#define RUBY_INTERNAL_EVENT_FREEOBJ 0x200000

Object swept.

Definition at line 94 of file event.h.

◆ RUBY_INTERNAL_EVENT_GC_END_MARK

#define RUBY_INTERNAL_EVENT_GC_END_MARK 0x800000

GC ended mark phase.

Definition at line 96 of file event.h.

◆ RUBY_INTERNAL_EVENT_GC_END_SWEEP

#define RUBY_INTERNAL_EVENT_GC_END_SWEEP 0x1000000

GC ended sweep phase.

Definition at line 97 of file event.h.

◆ RUBY_INTERNAL_EVENT_GC_ENTER

#define RUBY_INTERNAL_EVENT_GC_ENTER 0x2000000

gc_enter() is called.

Definition at line 98 of file event.h.

◆ RUBY_INTERNAL_EVENT_GC_EXIT

#define RUBY_INTERNAL_EVENT_GC_EXIT 0x4000000

gc_exit() is called.

Definition at line 99 of file event.h.

◆ RUBY_INTERNAL_EVENT_GC_START

#define RUBY_INTERNAL_EVENT_GC_START 0x400000

GC started.

Definition at line 95 of file event.h.

◆ RUBY_INTERNAL_EVENT_MASK

#define RUBY_INTERNAL_EVENT_MASK 0xffff0000

Bitmask of internal events.

Definition at line 101 of file event.h.

◆ RUBY_INTERNAL_EVENT_NEWOBJ

#define RUBY_INTERNAL_EVENT_NEWOBJ 0x100000

Object allocated.

Definition at line 93 of file event.h.

◆ RUBY_INTERNAL_EVENT_OBJSPACE_MASK

#define RUBY_INTERNAL_EVENT_OBJSPACE_MASK 0x7f00000

Bitmask of GC events.

Definition at line 100 of file event.h.

◆ RUBY_INTERNAL_EVENT_SWITCH

#define RUBY_INTERNAL_EVENT_SWITCH 0x040000

Thread switched.

Definition at line 90 of file event.h.

Typedef Documentation

◆ rb_event_flag_t

typedef uint32_t rb_event_flag_t

Represents event(s).

As the name implies events are bit flags.

Definition at line 108 of file event.h.

◆ rb_event_hook_func_t

typedef void(* rb_event_hook_func_t) (rb_event_flag_t evflag, VALUE data, VALUE self, ID mid, VALUE klass)

Type of event hooks.

When an event happens registered functions are kicked with appropriate parameters.

Parameters

[in]	evflag	The kind of event that happened.
[in]	data	The `data` passed to rb_add_event_hook().
[in]	self	Current receiver.
[in]	mid	Name of the current method.
[in]	klass	Current class.

Definition at line 120 of file event.h.

Function Documentation

◆ rb_add_event_hook()

void rb_add_event_hook	(	rb_event_hook_func_t	func,
		rb_event_flag_t	events,
		VALUE	data
	)

Registers an event hook function.

Parameters

[in]	func	A callback.
[in]	events	A set of events that `func` should run.
[in]	data	Passed as-is to `func`.

Definition at line 207 of file vm_trace.c.

◆ rb_remove_event_hook()

int rb_remove_event_hook ( rb_event_hook_func_t func )

Removes the passed function from the list of event hooks.

Parameters

[in] func A callback.

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

(348a53415339076afc4a02fcd09f3ae36e9c4c61)

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ RB_EVENT_HOOKS_HAVE_CALLBACK_DATA

◆ RUBY_EVENT_ALL

◆ RUBY_EVENT_B_CALL

◆ RUBY_EVENT_B_RETURN

◆ RUBY_EVENT_C_CALL

◆ RUBY_EVENT_C_RETURN

◆ RUBY_EVENT_CALL

◆ RUBY_EVENT_CLASS

◆ RUBY_EVENT_END

◆ RUBY_EVENT_FIBER_SWITCH

◆ RUBY_EVENT_LINE

◆ RUBY_EVENT_NONE

◆ RUBY_EVENT_RAISE

◆ RUBY_EVENT_RESCUE

◆ RUBY_EVENT_RESERVED_FOR_INTERNAL_USE

◆ RUBY_EVENT_RETURN

◆ RUBY_EVENT_SCRIPT_COMPILED

◆ RUBY_EVENT_THREAD_BEGIN

◆ RUBY_EVENT_THREAD_END

◆ RUBY_EVENT_TRACEPOINT_ALL

◆ RUBY_INTERNAL_EVENT_FREEOBJ

◆ RUBY_INTERNAL_EVENT_GC_END_MARK

◆ RUBY_INTERNAL_EVENT_GC_END_SWEEP

◆ RUBY_INTERNAL_EVENT_GC_ENTER

◆ RUBY_INTERNAL_EVENT_GC_EXIT

◆ RUBY_INTERNAL_EVENT_GC_START

◆ RUBY_INTERNAL_EVENT_MASK

◆ RUBY_INTERNAL_EVENT_NEWOBJ

◆ RUBY_INTERNAL_EVENT_OBJSPACE_MASK

◆ RUBY_INTERNAL_EVENT_SWITCH

Typedef Documentation

◆ rb_event_flag_t

◆ rb_event_hook_func_t

Function Documentation

◆ rb_add_event_hook()

◆ rb_remove_event_hook()