#ifndef RBIMPL_EVENT_H /*-*-C++-*-vi:se ft=cpp:*/ #define RBIMPL_EVENT_H /** * @file * @author Ruby developers * @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. * @brief Debugging and tracing APIs. */ #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" /* These macros are not enums because they are wider than int.*/ /** * @name 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. */ /** @} */ /** * @name 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. */ /** @} */ /** * @name Special events * * @internal * * These bits are actually used internally. See vm_core.h if you are curious. * * @endinternal * * @{ */ #define RUBY_EVENT_RESERVED_FOR_INTERNAL_USE 0x030000 /**< Opaque bits. */ /** @} */ /** * @name 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{RUBY_INTERNAL_EVENT_SWITCH} */ /* 0x080000 */ #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. */ /** @} */ /** * Represents event(s). As the name implies events are bit flags. */ typedef uint32_t rb_event_flag_t; /** * Type of event hooks. When an event happens registered functions are kicked * with appropriate parameters. * * @param[in] evflag The kind of event that happened. * @param[in] data The `data` passed to rb_add_event_hook(). * @param[in] self Current receiver. * @param[in] mid Name of the current method. * @param[in] klass Current class. */ typedef void (*rb_event_hook_func_t)(rb_event_flag_t evflag, VALUE data, VALUE self, ID mid, VALUE klass); /** * @private * * @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. */ #define RB_EVENT_HOOKS_HAVE_CALLBACK_DATA 1 RBIMPL_SYMBOL_EXPORT_BEGIN() /** * Registers an event hook function. * * @param[in] func A callback. * @param[in] events A set of events that `func` should run. * @param[in] data Passed as-is to `func`. */ void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data); /** * Removes the passed function from the list of event hooks. * * @param[in] func A callback. * @return 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. * * @internal * * @shyouhei doesn't know if this is an Easter egg or an official feature, but * you can pass 0 to the argument. That effectively swipes everything out from * the hook list. */ int rb_remove_event_hook(rb_event_hook_func_t func); RBIMPL_SYMBOL_EXPORT_END() #endif /* RBIMPL_EVENT_H */