ruby-changes:67735
From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:01:18 +0900 (JST)
Subject: [ruby-changes:67735] ee94fb44f4 (master): include/ruby/internal/event.h: add doxygen
https://git.ruby-lang.org/ruby.git/commit/?id=ee94fb44f4 From ee94fb44f4ea0c75203bd0e99909360c81f971fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?= <shyouhei@r...> Date: Thu, 21 Jan 2021 09:36:11 +0900 Subject: include/ruby/internal/event.h: add doxygen Must not be a bad idea to improve documents. [ci skip] --- include/ruby/internal/event.h | 155 +++++++++++++++++++++++++++++++----------- 1 file changed, 117 insertions(+), 38 deletions(-) diff --git a/include/ruby/internal/event.h b/include/ruby/internal/event.h index 1b541e9..04b137a 100644 --- a/include/ruby/internal/event.h +++ b/include/ruby/internal/event.h @@ -23,53 +23,132 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/event.h#L23 #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.*/ + +/** + * @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. */ -/* 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 - -/* 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 - -/* 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 + +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); -int rb_remove_event_hook(rb_event_hook_func_t func); +/** + * 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 */ -- cgit v1.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/