From 2d37b44603f2031f0e95073ab77b418142c9eddd Mon Sep 17 00:00:00 2001 From: Jean Boussier Date: Wed, 6 Sep 2023 09:47:07 +0200 Subject: Document that thread event hooks are called without the GVL Except for the `RESUMED` event. --- include/ruby/thread.h | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) (limited to 'include') diff --git a/include/ruby/thread.h b/include/ruby/thread.h index 0b5b1ca0f3..3753a4c06a 100644 --- a/include/ruby/thread.h +++ b/include/ruby/thread.h @@ -190,11 +190,41 @@ void *rb_nogvl(void *(*func)(void *), void *data1, */ #define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_ -#define RUBY_INTERNAL_THREAD_EVENT_STARTED 1 << 0 /** thread started */ +/** + * Triggered when a new thread is started. + * + * @note The callback will be called *without* the GVL held. + */ +#define RUBY_INTERNAL_THREAD_EVENT_STARTED 1 << 0 + +/** +* Triggered when a thread attempt to acquire the GVL. +* +* @note The callback will be called *without* the GVL held. +*/ #define RUBY_INTERNAL_THREAD_EVENT_READY 1 << 1 /** acquiring GVL */ + +/** + * Triggered when a thread successfuly acquired the GVL. + * + * @note The callback will be called *with* the GVL held. + */ #define RUBY_INTERNAL_THREAD_EVENT_RESUMED 1 << 2 /** acquired GVL */ + +/** + * Triggered when a thread released the GVL. + * + * @note The callback will be called *without* the GVL held. + */ #define RUBY_INTERNAL_THREAD_EVENT_SUSPENDED 1 << 3 /** released GVL */ + +/** + * Triggered when a thread exits. + * + * @note The callback will be called *without* the GVL held. + */ #define RUBY_INTERNAL_THREAD_EVENT_EXITED 1 << 4 /** thread terminated */ + #define RUBY_INTERNAL_THREAD_EVENT_MASK 0xff /** All Thread events */ typedef void rb_internal_thread_event_data_t; // for future extension. @@ -212,6 +242,8 @@ typedef struct rb_internal_thread_event_hook rb_internal_thread_event_hook_t; * @param[in] data Passed as-is to `func`. * @return An opaque pointer to the hook, to unregister it later. * @note This functionality is a noop on Windows. + * @note The callback will be called without the GVL held, except for the + RESUMED event. * @warning This function MUST not be called from a thread event callback. */ rb_internal_thread_event_hook_t *rb_internal_thread_add_event_hook( -- cgit v1.2.3