include/ruby/internal/event.h: add doxygen
Must not be a bad idea to improve documents. [ci skip]
This commit is contained in:
卜部昌平
parent
99c3328edc
commit
ee94fb44f4
Notes:
git
2021-09-10 20:01:47 +09:00
@ -23,53 +23,132 @@
|
||||
#include "ruby/internal/dllexport.h"
|
||||
#include "ruby/internal/value.h"
|
||||
|
||||
RBIMPL_SYMBOL_EXPORT_BEGIN()
|
||||
/* These macros are not enums because they are wider than int.*/
|
||||
|
||||
/* traditional set_trace_func events */
|
||||
#define RUBY_EVENT_NONE 0x0000
|
||||
#define RUBY_EVENT_LINE 0x0001
|
||||
#define RUBY_EVENT_CLASS 0x0002
|
||||
#define RUBY_EVENT_END 0x0004
|
||||
#define RUBY_EVENT_CALL 0x0008
|
||||
#define RUBY_EVENT_RETURN 0x0010
|
||||
#define RUBY_EVENT_C_CALL 0x0020
|
||||
#define RUBY_EVENT_C_RETURN 0x0040
|
||||
#define RUBY_EVENT_RAISE 0x0080
|
||||
#define RUBY_EVENT_ALL 0x00ff
|
||||
/**
|
||||
* @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. */
|
||||
|
||||
/* for TracePoint extended events */
|
||||
#define RUBY_EVENT_B_CALL 0x0100
|
||||
#define RUBY_EVENT_B_RETURN 0x0200
|
||||
#define RUBY_EVENT_THREAD_BEGIN 0x0400
|
||||
#define RUBY_EVENT_THREAD_END 0x0800
|
||||
#define RUBY_EVENT_FIBER_SWITCH 0x1000
|
||||
#define RUBY_EVENT_SCRIPT_COMPILED 0x2000
|
||||
#define RUBY_EVENT_TRACEPOINT_ALL 0xffff
|
||||
/** @} */
|
||||
|
||||
/* special events */
|
||||
#define RUBY_EVENT_RESERVED_FOR_INTERNAL_USE 0x030000
|
||||
/**
|
||||
* @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. */
|
||||
|
||||
/* internal events */
|
||||
#define RUBY_INTERNAL_EVENT_SWITCH 0x040000
|
||||
#define RUBY_EVENT_SWITCH 0x040000 /* obsolete name. this macro is for compatibility */
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @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
|
||||
#define RUBY_INTERNAL_EVENT_FREEOBJ 0x200000
|
||||
#define RUBY_INTERNAL_EVENT_GC_START 0x400000
|
||||
#define RUBY_INTERNAL_EVENT_GC_END_MARK 0x800000
|
||||
#define RUBY_INTERNAL_EVENT_GC_END_SWEEP 0x1000000
|
||||
#define RUBY_INTERNAL_EVENT_GC_ENTER 0x2000000
|
||||
#define RUBY_INTERNAL_EVENT_GC_EXIT 0x4000000
|
||||
#define RUBY_INTERNAL_EVENT_OBJSPACE_MASK 0x7f00000
|
||||
#define RUBY_INTERNAL_EVENT_MASK 0xffff0000
|
||||
#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
|
||||
void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data);
|
||||
int rb_remove_event_hook(rb_event_hook_func_t func);
|
||||
|
||||
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 */
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user