Ruby: include/ruby/internal/event.h File Reference

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

Macros | Typedefs | Functions
event.h File Reference

Debugging and tracing APIs. More...

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

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.
#define | RUBY_EVENT_LINE 0x0001
| Encountered a new line.
#define | RUBY_EVENT_CLASS 0x0002
| Encountered a new class.
#define | RUBY_EVENT_END 0x0004
| Encountered an end of a class clause.
#define | RUBY_EVENT_CALL 0x0008
| A method, written in Ruby, is called.
#define | RUBY_EVENT_RETURN 0x0010
| Encountered a `return` statement.
#define | RUBY_EVENT_C_CALL 0x0020
| A method, written in C, is called.
#define | RUBY_EVENT_C_RETURN 0x0040
| Return from a method, written in C.
#define | RUBY_EVENT_RAISE 0x0080
| Encountered a `raise` statement.
#define | RUBY_EVENT_ALL 0x00ff
| Bitmask of traditional events.
TracePoint extended events
#define | RUBY_EVENT_B_CALL 0x0100
| Encountered an `yield` statement.
#define | RUBY_EVENT_B_RETURN 0x0200
| Encountered a `next` statement.
#define | RUBY_EVENT_THREAD_BEGIN 0x0400
| Encountered a new thread.
#define | RUBY_EVENT_THREAD_END 0x0800
| Encountered an end of a thread.
#define | RUBY_EVENT_FIBER_SWITCH 0x1000
| Encountered a `Fiber#yield`.
#define | RUBY_EVENT_SCRIPT_COMPILED 0x2000
| Encountered an `eval`.
#define | RUBY_EVENT_TRACEPOINT_ALL 0xffff
| Bitmask of extended events.
Special events
#define | RUBY_EVENT_RESERVED_FOR_INTERNAL_USE 0x030000
| Opaque bits.
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.
#define | RUBY_EVENT_SWITCH 0x040000
| Old name of RUBY_INTERNAL_EVENT_SWITCH.
#define | RUBY_INTERNAL_EVENT_NEWOBJ 0x100000
| Object allocated.
#define | RUBY_INTERNAL_EVENT_FREEOBJ 0x200000
| Object swept.
#define | RUBY_INTERNAL_EVENT_GC_START 0x400000
| GC started.
#define | RUBY_INTERNAL_EVENT_GC_END_MARK 0x800000
| GC ended mark phase.
#define | RUBY_INTERNAL_EVENT_GC_END_SWEEP 0x1000000
| GC ended sweep phase.
#define | RUBY_INTERNAL_EVENT_GC_ENTER 0x2000000
| `gc_enter()` is called.
#define | RUBY_INTERNAL_EVENT_GC_EXIT 0x4000000
| `gc_exit()` is called.
#define | RUBY_INTERNAL_EVENT_OBJSPACE_MASK 0x7f00000
| Bitmask of GC events.
#define | RUBY_INTERNAL_EVENT_MASK 0xffff0000
| Bitmask of internal events.

## Typedefs
typedef uint32_t | rb_event_flag_t
| Represents event(s).
typedef void(* | rb_event_hook_func_t) (rb_event_flag_t evflag, VALUE data, VALUE self, ID mid, VALUE klass)
| Type of event hooks.

## Functions
void | rb_add_event_hook (rb_event_hook_func_t func, rb_event_flag_t events, VALUE data)
| Registers an event hook function.
int | rb_remove_event_hook (rb_event_hook_func_t func)
| Removes the passed function from the list of event hooks.

## 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 124 of file event.h.

## ◆ RUBY_EVENT_ALL

#define RUBY_EVENT_ALL 0x00ff

Bitmask of traditional events.

Definition at line 42 of file event.h.

## ◆ RUBY_EVENT_B_CALL

#define RUBY_EVENT_B_CALL 0x0100

Encountered an `yield` statement.

Definition at line 51 of file event.h.

## ◆ RUBY_EVENT_B_RETURN

#define RUBY_EVENT_B_RETURN 0x0200

Encountered a `next` statement.

Definition at line 52 of file event.h.

Referenced by rb_tracearg_return_value().

## ◆ RUBY_EVENT_C_CALL

#define RUBY_EVENT_C_CALL 0x0020

A method, written in C, is called.

Definition at line 39 of file event.h.

Referenced by rb_tracearg_binding().

## ◆ RUBY_EVENT_C_RETURN

#define RUBY_EVENT_C_RETURN 0x0040

Return from a method, written in C.

Definition at line 40 of file event.h.

Referenced by rb_tracearg_binding(), and rb_tracearg_return_value().

## ◆ RUBY_EVENT_CALL

#define RUBY_EVENT_CALL 0x0008

A method, written in Ruby, is called.

Definition at line 37 of file event.h.

## ◆ RUBY_EVENT_CLASS

#define RUBY_EVENT_CLASS 0x0002

Encountered a new class.

Definition at line 35 of file event.h.

## ◆ RUBY_EVENT_END

#define RUBY_EVENT_END 0x0004

Encountered an end of a class clause.

Definition at line 36 of file event.h.

## ◆ RUBY_EVENT_FIBER_SWITCH

#define RUBY_EVENT_FIBER_SWITCH 0x1000

Encountered a `Fiber#yield`.

Definition at line 55 of file event.h.

## ◆ RUBY_EVENT_LINE

#define RUBY_EVENT_LINE 0x0001

Encountered a new line.

Definition at line 34 of file event.h.

## ◆ RUBY_EVENT_NONE

#define RUBY_EVENT_NONE 0x0000

No events.

Definition at line 33 of file event.h.

## ◆ RUBY_EVENT_RAISE

#define RUBY_EVENT_RAISE 0x0080

Encountered a `raise` statement.

Definition at line 41 of file event.h.

Referenced by rb_tracearg_raised_exception().

## ◆ RUBY_EVENT_RESERVED_FOR_INTERNAL_USE

#define RUBY_EVENT_RESERVED_FOR_INTERNAL_USE 0x030000

Opaque bits.

Definition at line 72 of file event.h.

## ◆ RUBY_EVENT_RETURN

#define RUBY_EVENT_RETURN 0x0010

Encountered a `return` statement.

Definition at line 38 of file event.h.

Referenced by rb_tracearg_return_value().

## ◆ RUBY_EVENT_SCRIPT_COMPILED

#define RUBY_EVENT_SCRIPT_COMPILED 0x2000

Encountered an `eval`.

Definition at line 56 of file event.h.

## ◆ RUBY_EVENT_THREAD_BEGIN

#define RUBY_EVENT_THREAD_BEGIN 0x0400

Encountered a new thread.

Definition at line 53 of file event.h.

## ◆ RUBY_EVENT_THREAD_END

#define RUBY_EVENT_THREAD_END 0x0800

Encountered an end of a thread.

Definition at line 54 of file event.h.

## ◆ RUBY_EVENT_TRACEPOINT_ALL

#define RUBY_EVENT_TRACEPOINT_ALL 0xffff

Bitmask of extended events.

Definition at line 57 of file event.h.

## ◆ RUBY_INTERNAL_EVENT_FREEOBJ

#define RUBY_INTERNAL_EVENT_FREEOBJ 0x200000

Object swept.

Definition at line 89 of file event.h.

Referenced by rb_tracearg_object().

## ◆ RUBY_INTERNAL_EVENT_GC_END_MARK

#define RUBY_INTERNAL_EVENT_GC_END_MARK 0x800000

GC ended mark phase.

Definition at line 91 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 92 of file event.h.

## ◆ RUBY_INTERNAL_EVENT_GC_ENTER

#define RUBY_INTERNAL_EVENT_GC_ENTER 0x2000000

`gc_enter()` is called.

Definition at line 93 of file event.h.

## ◆ RUBY_INTERNAL_EVENT_GC_EXIT

#define RUBY_INTERNAL_EVENT_GC_EXIT 0x4000000

`gc_exit()` is called.

Definition at line 94 of file event.h.

## ◆ RUBY_INTERNAL_EVENT_GC_START

#define RUBY_INTERNAL_EVENT_GC_START 0x400000

GC started.

Definition at line 90 of file event.h.

## ◆ RUBY_INTERNAL_EVENT_MASK

#define RUBY_INTERNAL_EVENT_MASK 0xffff0000

Bitmask of internal events.

Definition at line 96 of file event.h.

## ◆ RUBY_INTERNAL_EVENT_NEWOBJ

#define RUBY_INTERNAL_EVENT_NEWOBJ 0x100000

Object allocated.

Definition at line 88 of file event.h.

Referenced by rb_tracearg_object().

## ◆ RUBY_INTERNAL_EVENT_OBJSPACE_MASK

#define RUBY_INTERNAL_EVENT_OBJSPACE_MASK 0x7f00000

Bitmask of GC events.

Definition at line 95 of file event.h.

## ◆ RUBY_INTERNAL_EVENT_SWITCH

#define RUBY_INTERNAL_EVENT_SWITCH 0x040000

Thread switched.

Definition at line 85 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 103 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 115 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 185 of file vm_trace.c.

Referenced by rb_add_event_hook().

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

Referenced by rb_remove_event_hook().