Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Macros | Typedefs | Functions
event.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

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:

Go to the source code of 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
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]evflagThe kind of event that happened.
[in]dataThe data passed to rb_add_event_hook().
[in]selfCurrent receiver.
[in]midName of the current method.
[in]klassCurrent 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]funcA callback.
[in]eventsA set of events that func should run.
[in]dataPassed 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]funcA 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.