Ruby: include/ruby/thread.h Source File

Ruby 3.4.9p82 (2026-03-11 revision 76cca827ab52ab1d346a728f068d5b8da3e2952b)

thread.h
Go to the documentation of this file.
1#ifndef RUBY_THREAD_H /*-*-C++-*-vi:se ft=cpp:*/
2#define RUBY_THREAD_H 1
13#include "ruby/internal/attr/nonnull.h"
14#include "ruby/internal/intern/thread.h" /* rb_unblock_function_t */
15#include "ruby/internal/dllexport.h"
16
22
48#define RB_NOGVL_INTR_FAIL (0x1)
49
60#define RB_NOGVL_UBF_ASYNC_SAFE (0x2)
61
73#define RB_NOGVL_OFFLOAD_SAFE (0x4)
74
76
77 RBIMPL_SYMBOL_EXPORT_BEGIN()
78
79 RBIMPL_ATTR_NONNULL((1))
104void *rb_thread_call_with_gvl(void *(*func)(void *), void *data1);
105
106 RBIMPL_ATTR_NONNULL((1))
143void *rb_thread_call_without_gvl(void *(*func)(void *), void *data1,
144 rb_unblock_function_t *ubf, void *data2);
145
146 RBIMPL_ATTR_NONNULL((1))
167void *rb_thread_call_without_gvl2(void *(*func)(void *), void *data1,
168 rb_unblock_function_t *ubf, void *data2);
169
170/*
171 * XXX: unstable/unapproved - out-of-tree code should NOT not depend
172 * on this until it hits Ruby 2.6.1
173 */
174
175 RBIMPL_ATTR_NONNULL((1))
187void *rb_nogvl(void *(*func)(void *), void *data1,
188 rb_unblock_function_t *ubf, void *data2,
189 int flags);
190
198#define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_AFTER 0x01
199
204#define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_
205
217 bool rb_thread_lock_native_thread(void);
218
224#define RUBY_INTERNAL_THREAD_EVENT_STARTED 1 << 0
225
231#define RUBY_INTERNAL_THREAD_EVENT_READY 1 << 1
232
238#define RUBY_INTERNAL_THREAD_EVENT_RESUMED 1 << 2
239
245#define RUBY_INTERNAL_THREAD_EVENT_SUSPENDED 1 << 3
246
252#define RUBY_INTERNAL_THREAD_EVENT_EXITED 1 << 4
253
254#define RUBY_INTERNAL_THREAD_EVENT_MASK 0xff
255
256 typedef struct rb_internal_thread_event_data {
257 VALUE thread;
258} rb_internal_thread_event_data_t;
259
260typedef void (*rb_internal_thread_event_callback)(rb_event_flag_t event,
261 const rb_internal_thread_event_data_t *event_data,
262 void *user_data);
263typedef struct rb_internal_thread_event_hook rb_internal_thread_event_hook_t;
264
280rb_internal_thread_event_hook_t *rb_internal_thread_add_event_hook(
281 rb_internal_thread_event_callback func, rb_event_flag_t events,
282 void *data);
283
284
293 bool rb_internal_thread_remove_event_hook(
294 rb_internal_thread_event_hook_t * hook);
295
296
297typedef int rb_internal_thread_specific_key_t;
298#define RB_INTERNAL_THREAD_SPECIFIC_KEY_MAX 8
320rb_internal_thread_specific_key_t rb_internal_thread_specific_key_create(void);
321
327void *rb_internal_thread_specific_get(VALUE thread_val, rb_internal_thread_specific_key_t key);
328
334void rb_internal_thread_specific_set(VALUE thread_val, rb_internal_thread_specific_key_t key, void *data);
335
336 RBIMPL_SYMBOL_EXPORT_END()
337
338#endif /* RUBY_THREAD_H */
dllexport.h
Tweaking visibility of C variables/functions.
RBIMPL_SYMBOL_EXPORT_END
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition dllexport.h:74
RBIMPL_SYMBOL_EXPORT_BEGIN
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:65
rb_event_flag_t
uint32_t rb_event_flag_t
Represents event(s).
Definition event.h:108
thread.h
Public APIs related to rb_cThread.
rb_unblock_function_t
void rb_unblock_function_t(void *)
This is the type of UBFs.
Definition thread.h:336
rb_internal_thread_specific_get
void * rb_internal_thread_specific_get(VALUE thread_val, rb_internal_thread_specific_key_t key)
Get thread and tool specific data.
Definition thread.c:5960
rb_internal_thread_specific_set
void rb_internal_thread_specific_set(VALUE thread_val, rb_internal_thread_specific_key_t key, void *data)
Set thread and tool specific data.
Definition thread.c:5973
rb_internal_thread_specific_key_create
rb_internal_thread_specific_key_t rb_internal_thread_specific_key_create(void)
Create a key to store thread specific data.
Definition thread.c:5932
rb_nogvl
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 behav...
Definition thread.c:1539
rb_thread_call_with_gvl
void * rb_thread_call_with_gvl(void *(*func)(void *), void *data1)
(Re-)acquires the GVL.
Definition thread.c:1904
rb_internal_thread_add_event_hook
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.
rb_thread_call_without_gvl2
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.
Definition thread.c:1678
rb_thread_lock_native_thread
bool rb_thread_lock_native_thread(void)
Declare the current Ruby thread should acquire a dedicated native thread on M:N thread scheduler.
rb_thread_call_without_gvl
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.
Definition thread.c:1685
rb_internal_thread_remove_event_hook
bool rb_internal_thread_remove_event_hook(rb_internal_thread_event_hook_t *hook)
Unregister the passed hook.
nonnull.h
Defines RBIMPL_ATTR_NONNULL.
RBIMPL_ATTR_NONNULL
#define RBIMPL_ATTR_NONNULL(list)
Wraps (or simulates) __attribute__((nonnull)).
Definition nonnull.h:30
rb_internal_thread_event_data
Definition thread.h:256
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40