Ruby
3.4.0dev (2024-11-22 revision 37a72b0150ec36b4ea27175039afc28c62207b0c)
|
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/intern/thread.h"
#include "ruby/internal/dllexport.h"
Go to the source code of this file.
Data Structures | |
struct | rb_internal_thread_event_data |
Macros | |
#define | RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_AFTER 0x01 |
#define | RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_ |
#define | RUBY_INTERNAL_THREAD_EVENT_STARTED 1 << 0 |
Triggered when a new thread is started. More... | |
#define | RUBY_INTERNAL_THREAD_EVENT_READY 1 << 1 /** acquiring GVL */ |
Triggered when a thread attempt to acquire the GVL. More... | |
#define | RUBY_INTERNAL_THREAD_EVENT_RESUMED 1 << 2 /** acquired GVL */ |
Triggered when a thread successfully acquired the GVL. More... | |
#define | RUBY_INTERNAL_THREAD_EVENT_SUSPENDED 1 << 3 /** released GVL */ |
Triggered when a thread released the GVL. More... | |
#define | RUBY_INTERNAL_THREAD_EVENT_EXITED 1 << 4 /** thread terminated */ |
Triggered when a thread exits. More... | |
#define | RUBY_INTERNAL_THREAD_EVENT_MASK 0xff /** All Thread events */ |
#define | RB_INTERNAL_THREAD_SPECIFIC_KEY_MAX 8 |
Flags for rb_nogvl() | |
#define | RB_NOGVL_INTR_FAIL (0x1) |
Passing this flag to rb_nogvl() prevents it from checking interrupts. More... | |
#define | RB_NOGVL_UBF_ASYNC_SAFE (0x2) |
Passing this flag to rb_nogvl() indicates that the passed UBF is async-signal-safe. More... | |
#define | RB_NOGVL_OFFLOAD_SAFE (0x4) |
Passing this flag to rb_nogvl() indicates that the passed function is safe to offload to a background thread or work pool. More... | |
Typedefs | |
typedef struct rb_internal_thread_event_data | rb_internal_thread_event_data_t |
typedef void(* | rb_internal_thread_event_callback) (rb_event_flag_t event, const rb_internal_thread_event_data_t *event_data, void *user_data) |
typedef struct rb_internal_thread_event_hook | rb_internal_thread_event_hook_t |
typedef int | rb_internal_thread_specific_key_t |
Functions | |
void * | rb_thread_call_with_gvl (void *(*func)(void *), void *data1) |
(Re-)acquires the GVL. More... | |
void * | rb_thread_call_without_gvl (void *(*func)(void *), void *data1, rb_unblock_function_t *ubf, void *data2) |
Allows the passed function to run in parallel with other Ruby threads. More... | |
void * | rb_thread_call_without_gvl2 (void *(*func)(void *), void *data1, rb_unblock_function_t *ubf, void *data2) |
Identical to rb_thread_call_without_gvl(), except it does not interface with signals etc. More... | |
void * | rb_nogvl (void *(*func)(void *), void *data1, rb_unblock_function_t *ubf, void *data2, int flags) |
Identical to rb_thread_call_without_gvl(), except it additionally takes "flags" that change the behaviour. More... | |
bool | rb_thread_lock_native_thread (void) |
Declare the current Ruby thread should acquire a dedicated native thread on M:N thread scheduler. More... | |
rb_internal_thread_event_hook_t * | rb_internal_thread_add_event_hook (rb_internal_thread_event_callback func, rb_event_flag_t events, void *data) |
Registers a thread event hook function. More... | |
bool | rb_internal_thread_remove_event_hook (rb_internal_thread_event_hook_t *hook) |
Unregister the passed hook. More... | |
rb_internal_thread_specific_key_t | rb_internal_thread_specific_key_create (void) |
Create a key to store thread specific data. More... | |
void * | rb_internal_thread_specific_get (VALUE thread_val, rb_internal_thread_specific_key_t key) |
Get thread and tool specific data. More... | |
void | rb_internal_thread_specific_set (VALUE thread_val, rb_internal_thread_specific_key_t key, void *data) |
Set thread and tool specific data. More... | |
Definition in file thread.h.
#define RB_NOGVL_INTR_FAIL (0x1) |
Passing this flag to rb_nogvl() prevents it from checking interrupts.
Interrupts can impact your program negatively. For instance consider following callback function:
Here, if it gets interrupted at (a) or (b), read(2)
is cancelled and this function leaks memory (which is not a good thing of course, but...). But if it gets interrupted at (c), where read(2)
is already done, interruption is way more catastrophic because what was read gets lost. To reroute this kind of problem you should set this flag. And check interrupts elsewhere at your own risk.
#define RB_NOGVL_OFFLOAD_SAFE (0x4) |
Passing this flag to rb_nogvl() indicates that the passed function is safe to offload to a background thread or work pool.
In other words, the function is safe to run using a fiber scheduler's blocking_operation_wait
. hook.
If your function depends on thread-local storage, or thread-specific data operations/data structures, you should not set this flag, as these operations may behave differently (or fail) when run in a different thread/context (e.g. unlocking a mutex).
#define RB_NOGVL_UBF_ASYNC_SAFE (0x2) |
Passing this flag to rb_nogvl() indicates that the passed UBF is async-signal-safe.
An UBF could be async safe, and that makes things simpler. However async unsafe UBFs are just okay. If unsure, you can safely leave it unspecified.
#define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_ |
#define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_AFTER 0x01 |
Exists here for backwards compatibility only. You can safely forget about it.
#define RUBY_INTERNAL_THREAD_EVENT_EXITED 1 << 4 /** thread terminated */ |
#define RUBY_INTERNAL_THREAD_EVENT_READY 1 << 1 /** acquiring GVL */ |
#define RUBY_INTERNAL_THREAD_EVENT_RESUMED 1 << 2 /** acquired GVL */ |
#define RUBY_INTERNAL_THREAD_EVENT_STARTED 1 << 0 |
#define RUBY_INTERNAL_THREAD_EVENT_SUSPENDED 1 << 3 /** released GVL */ |
rb_internal_thread_event_hook_t* rb_internal_thread_add_event_hook | ( | rb_internal_thread_event_callback | func, |
rb_event_flag_t | events, | ||
void * | data | ||
) |
Registers a thread event hook function.
[in] | func | A callback. |
[in] | events | A set of events that func should run. |
[in] | data | Passed as-is to func . |
event_data->thread
. bool rb_internal_thread_remove_event_hook | ( | rb_internal_thread_event_hook_t * | hook | ) |
Unregister the passed hook.
[in] | hook. | The hook to unregister. |
void* rb_internal_thread_specific_get | ( | VALUE | thread_val, |
rb_internal_thread_specific_key_t | key | ||
) |
rb_internal_thread_specific_key_t rb_internal_thread_specific_key_create | ( | void | ) |
Create a key to store thread specific data.
These APIs are designed for tools using rb_internal_thread_event_hook APIs.
Note that only RB_INTERNAL_THREAD_SPECIFIC_KEY_MAX
keys can be created. raises ThreadError
if exceeded.
Usage: // at initialize time: int tool_key; // gvar Init_tool() { tool_key = rb_internal_thread_specific_key_create(); }
// at any timing: rb_internal_thread_specific_set(thread, tool_key, per_thread_data); ... per_thread_data = rb_internal_thread_specific_get(thread, tool_key);
void rb_internal_thread_specific_set | ( | VALUE | thread_val, |
rb_internal_thread_specific_key_t | key, | ||
void * | data | ||
) |
void* rb_nogvl | ( | void *(*)(void *) | func, |
void * | data1, | ||
rb_unblock_function_t * | ubf, | ||
void * | data2, | ||
int | flags | ||
) |
Identical to rb_thread_call_without_gvl(), except it additionally takes "flags" that change the behaviour.
[in] | func | A function to call without GVL. |
[in,out] | data1 | Passed as-is to func . |
[in] | ubf | An UBF to cancel func . |
[in,out] | data2 | Passed as-is to ubf . |
[in] | flags | Flags. |
func
returned, or 0 in case func
did not return. Definition at line 1537 of file thread.c.
Referenced by rb_thread_call_without_gvl2().
void* rb_thread_call_with_gvl | ( | void *(*)(void *) | func, |
void * | data1 | ||
) |
(Re-)acquires the GVL.
This manoeuvre makes it possible for an out-of-GVL routine to one-shot call a ruby method.
What this function does:
[in] | func | What to call with GVL. |
[in,out] | data1 | Passed as-is to func . |
func
. func
must not return a Ruby object. If it did such return value would escape from GC's scope; would not be marked. func
does not raise, by properly rescuing everything using e.g. rb_protect(). void* rb_thread_call_without_gvl | ( | void *(*)(void *) | func, |
void * | data1, | ||
rb_unblock_function_t * | ubf, | ||
void * | data2 | ||
) |
Allows the passed function to run in parallel with other Ruby threads.
What this function does:
In case other threads interfaced with this thread using rb_thread_kill() etc., the passed UBF is additionally called. See rb_unblock_function_t for details.
Unlike rb_thread_call_without_gvl2() this function also reacts to signals etc.
[in] | func | A function to call without GVL. |
[in,out] | data1 | Passed as-is to func . |
[in] | ubf | An UBF to cancel func . |
[in,out] | data2 | Passed as-is to ubf . |
func
returned, or 0 in case ubf
cancelled func
. func
, it might be faster to just call func
with blocking everything else. Be sure to benchmark your code to see if it is actually worth releasing the GVL. void* rb_thread_call_without_gvl2 | ( | void *(*)(void *) | func, |
void * | data1, | ||
rb_unblock_function_t * | ubf, | ||
void * | data2 | ||
) |
Identical to rb_thread_call_without_gvl(), except it does not interface with signals etc.
As described in RB_NOGVL_INTR_FAIL, interrupts can hurt you. In case this function detects an interrupt, it returns immediately. You can record progress of your callback and check it after returning from this function.
What this function does:
[in] | func | A function to call without GVL. |
[in,out] | data1 | Passed as-is to func . |
[in] | ubf | An UBF to cancel func . |
[in,out] | data2 | Passed as-is to ubf . |
func
returned, or 0 in case func
did not return. bool rb_thread_lock_native_thread | ( | void | ) |
Declare the current Ruby thread should acquire a dedicated native thread on M:N thread scheduler.
If a C extension (or a library which the extension relies on) should keep to run on a native thread (e.g. using thread-local-storage), this function allocates a dedicated native thread for the thread.
false
if the thread already running on a dedicated native thread. Otherwise true
.