Ruby: ractor_core.h Source File

Ruby 4.0.6p0 (2026-07-14 revision 03b6d3f8898a28604fe6cb00eae3226b821168f4)

ractor_core.h
1#include "internal/gc.h"
2#include "ruby/ruby.h"
3#include "ruby/ractor.h"
4#include "vm_core.h"
5#include "id_table.h"
6#include "vm_debug.h"
7
8#ifndef RACTOR_CHECK_MODE
9#define RACTOR_CHECK_MODE (VM_CHECK_MODE || RUBY_DEBUG) && (SIZEOF_UINT64_T == SIZEOF_VALUE)
10#endif
11
12// experimental flag because it is not sure it is the common pattern
13#define RUBY_TYPED_FROZEN_SHAREABLE_NO_REC RUBY_FL_FINALIZE
14
15 struct rb_ractor_sync {
16 // ractor lock
17 rb_nativethread_lock_t lock;
18
19#if RACTOR_CHECK_MODE > 0
20 VALUE locked_by;
21#endif
22
23#ifndef RUBY_THREAD_PTHREAD_H
24 rb_nativethread_cond_t wakeup_cond;
25#endif
26
27 // incoming messages
28 struct ractor_queue *recv_queue;
29
30 // waiting threads for receiving
31 struct ccan_list_head waiters;
32
33 // ports
34 VALUE default_port_value;
35 struct st_table *ports;
36 size_t next_port_id;
37
38 // monitors
39 struct ccan_list_head monitors;
40
41 // value
42 rb_ractor_t *successor;
43 VALUE legacy;
44 bool legacy_exc;
45};
46
47// created
48// | ready to run
49// ====================== inserted to vm->ractor
50// v
51// blocking <---+ all threads are blocking
52// | |
53// v |
54// running -----+
55// | all threads are terminated.
56// ====================== removed from vm->ractor
57// v
58// terminated
59//
60// status is protected by VM lock (global state)
61enum ractor_status {
62 ractor_created,
63 ractor_running,
64 ractor_blocking,
65 ractor_terminated,
66};
67
68 struct rb_ractor_struct {
69 struct rb_ractor_pub pub;
70 struct rb_ractor_sync sync;
71
72 // thread management
73 struct {
74 struct ccan_list_head set;
75 unsigned int cnt;
76 unsigned int blocking_cnt;
77 unsigned int sleeper;
78 struct rb_thread_sched sched;
79 rb_execution_context_t *running_ec;
80 rb_thread_t *main;
81 } threads;
82
83 VALUE thgroup_default;
84
85 VALUE name;
86 VALUE loc;
87
88 enum ractor_status status_;
89
90 struct ccan_list_node vmlr_node;
91
92 // ractor local data
93
94 rb_serial_t next_ec_serial;
95
96 st_table *local_storage;
97 struct rb_id_table *idkey_local_storage;
98 VALUE local_storage_store_lock;
99
100 VALUE r_stdin;
101 VALUE r_stdout;
102 VALUE r_stderr;
103 VALUE verbose;
104 VALUE debug;
105
106 bool malloc_gc_disabled;
107 void *newobj_cache;
108}; // rb_ractor_t is defined in vm_core.h
109
110
111static inline VALUE
112rb_ractor_self(const rb_ractor_t *r)
113{
114 return r->pub.self;
115}
116
117rb_ractor_t *rb_ractor_main_alloc(void);
118void rb_ractor_main_setup(rb_vm_t *vm, rb_ractor_t *main_ractor, rb_thread_t *main_thread);
119void rb_ractor_atexit(rb_execution_context_t *ec, VALUE result);
120void rb_ractor_atexit_exception(rb_execution_context_t *ec);
121void rb_ractor_teardown(rb_execution_context_t *ec);
122void rb_ractor_receive_parameters(rb_execution_context_t *ec, rb_ractor_t *g, int len, VALUE *ptr);
123void rb_ractor_send_parameters(rb_execution_context_t *ec, rb_ractor_t *g, VALUE args);
124
125 VALUE rb_thread_create_ractor(rb_ractor_t *g, VALUE args, VALUE proc); // defined in thread.c
126
127int rb_ractor_living_thread_num(const rb_ractor_t *);
128 VALUE rb_ractor_thread_list(void);
129bool rb_ractor_p(VALUE rv);
130
131void rb_ractor_living_threads_init(rb_ractor_t *r);
132void rb_ractor_living_threads_insert(rb_ractor_t *r, rb_thread_t *th);
133void rb_ractor_living_threads_remove(rb_ractor_t *r, rb_thread_t *th);
134void rb_ractor_blocking_threads_inc(rb_ractor_t *r, const char *file, int line); // TODO: file, line only for RUBY_DEBUG_LOG
135void rb_ractor_blocking_threads_dec(rb_ractor_t *r, const char *file, int line); // TODO: file, line only for RUBY_DEBUG_LOG
136
137void rb_ractor_vm_barrier_interrupt_running_thread(rb_ractor_t *r);
138void rb_ractor_terminate_interrupt_main_thread(rb_ractor_t *r);
139void rb_ractor_terminate_all(void);
140bool rb_ractor_main_p_(void);
141void rb_ractor_atfork(rb_vm_t *vm, rb_thread_t *th);
142void rb_ractor_terminate_atfork(rb_vm_t *vm, rb_ractor_t *th);
143 VALUE rb_ractor_require(VALUE feature, bool silent);
144 VALUE rb_ractor_autoload_load(VALUE space, ID id);
145
146 VALUE rb_ractor_ensure_shareable(VALUE obj, VALUE name);
147st_table *rb_ractor_targeted_hooks(rb_ractor_t *cr);
148
149RUBY_SYMBOL_EXPORT_BEGIN
150void rb_ractor_finish_marking(void);
151
152bool rb_ractor_shareable_p_continue(VALUE obj);
153
154// THIS FUNCTION SHOULD NOT CALL WHILE INCREMENTAL MARKING!!
155// This function is for T_DATA::free_func
156void rb_ractor_local_storage_delkey(rb_ractor_local_key_t key);
157
158RUBY_SYMBOL_EXPORT_END
159
160static inline bool
161rb_ractor_main_p(void)
162{
163 if (ruby_single_main_ractor) {
164 return true;
165 }
166 else {
167 return rb_ractor_main_p_();
168 }
169}
170
171static inline bool
172rb_ractor_status_p(rb_ractor_t *r, enum ractor_status status)
173{
174 return r->status_ == status;
175}
176
177static inline void
178rb_ractor_sleeper_threads_inc(rb_ractor_t *r)
179{
180 r->threads.sleeper++;
181}
182
183static inline void
184rb_ractor_sleeper_threads_dec(rb_ractor_t *r)
185{
186 r->threads.sleeper--;
187}
188
189static inline void
190rb_ractor_sleeper_threads_clear(rb_ractor_t *r)
191{
192 r->threads.sleeper = 0;
193}
194
195static inline int
196rb_ractor_sleeper_thread_num(rb_ractor_t *r)
197{
198 return r->threads.sleeper;
199}
200
201static inline void
202rb_ractor_thread_switch(rb_ractor_t *cr, rb_thread_t *th, bool always_reset)
203{
204 RUBY_DEBUG_LOG("th:%d->%u%s",
205 cr->threads.running_ec ? (int)rb_th_serial(cr->threads.running_ec->thread_ptr) : -1,
206 rb_th_serial(th), cr->threads.running_ec == th->ec ? " (same)" : "");
207
208 if (cr->threads.running_ec != th->ec || always_reset) {
209 th->running_time_us = 0;
210 }
211
212 if (cr->threads.running_ec != th->ec) {
213 if (0) {
214 ruby_debug_printf("rb_ractor_thread_switch ec:%p->%p\n",
215 (void *)cr->threads.running_ec, (void *)th->ec);
216 }
217 }
218 else {
219 return;
220 }
221
222 cr->threads.running_ec = th->ec;
223
224 VM_ASSERT(cr == GET_RACTOR());
225}
226
227#define rb_ractor_set_current_ec(cr, ec) rb_ractor_set_current_ec_(cr, ec, __FILE__, __LINE__)
228#ifdef RB_THREAD_LOCAL_SPECIFIER
229void rb_current_ec_set(rb_execution_context_t *ec);
230#endif
231
232static inline void
233rb_ractor_set_current_ec_(rb_ractor_t *cr, rb_execution_context_t *ec, const char *file, int line)
234{
235#ifdef RB_THREAD_LOCAL_SPECIFIER
236 rb_current_ec_set(ec);
237#else
238 native_tls_set(ruby_current_ec_key, ec);
239#endif
240 RUBY_DEBUG_LOG2(file, line, "ec:%p->%p", (void *)cr->threads.running_ec, (void *)ec);
241 VM_ASSERT(ec == NULL || cr->threads.running_ec != ec);
242 cr->threads.running_ec = ec;
243}
244
245void rb_vm_ractor_blocking_cnt_inc(rb_vm_t *vm, rb_ractor_t *cr, const char *file, int line);
246void rb_vm_ractor_blocking_cnt_dec(rb_vm_t *vm, rb_ractor_t *cr, const char *file, int line);
247
248static inline uint32_t
249rb_ractor_id(const rb_ractor_t *r)
250{
251 return r->pub.id;
252}
253
254static inline void
255rb_ractor_targeted_hooks_incr(rb_ractor_t *cr)
256{
257 cr->pub.targeted_hooks_cnt++;
258}
259
260static inline void
261rb_ractor_targeted_hooks_decr(rb_ractor_t *cr)
262{
263 RUBY_ASSERT(cr->pub.targeted_hooks_cnt > 0);
264 cr->pub.targeted_hooks_cnt--;
265}
266
267static inline unsigned int
268rb_ractor_targeted_hooks_cnt(rb_ractor_t *cr)
269{
270 return cr->pub.targeted_hooks_cnt;
271}
272
273#if RACTOR_CHECK_MODE > 0
274# define RACTOR_BELONGING_ID(obj) (*(uint32_t *)(((uintptr_t)(obj)) + rb_gc_obj_slot_size(obj)))
275
276uint32_t rb_ractor_current_id(void);
277
278static inline void
279rb_ractor_setup_belonging_to(VALUE obj, uint32_t rid)
280{
281 RACTOR_BELONGING_ID(obj) = rid;
282}
283
284static inline uint32_t
285rb_ractor_belonging(VALUE obj)
286{
287 if (SPECIAL_CONST_P(obj) || RB_OBJ_SHAREABLE_P(obj)) {
288 return 0;
289 }
290 else {
291 return RACTOR_BELONGING_ID(obj);
292 }
293}
294
295extern bool rb_ractor_ignore_belonging_flag;
296
297static inline VALUE
298rb_ractor_confirm_belonging(VALUE obj)
299{
300 if (rb_ractor_ignore_belonging_flag) return obj;
301
302 uint32_t id = rb_ractor_belonging(obj);
303
304 if (id == 0) {
305 if (UNLIKELY(!rb_ractor_shareable_p(obj))) {
306 rp(obj);
307 rb_bug("id == 0 but not shareable");
308 }
309 }
310 else if (UNLIKELY(id != rb_ractor_current_id())) {
311 if (rb_ractor_shareable_p(obj)) {
312 // ok
313 }
314 else {
315 rp(obj);
316 rb_bug("rb_ractor_confirm_belonging object-ractor id:%u, current-ractor id:%u", id, rb_ractor_current_id());
317 }
318 }
319 return obj;
320}
321
322static inline void
323rb_ractor_ignore_belonging(bool flag)
324{
325 rb_ractor_ignore_belonging_flag = flag;
326}
327
328#else
329#define rb_ractor_confirm_belonging(obj) obj
330#define rb_ractor_ignore_belonging(flag) (0)
331#endif
RUBY_ASSERT
#define RUBY_ASSERT(...)
Asserts that the given expression is truthy if and only if RUBY_DEBUG is truthy.
Definition assert.h:219
SPECIAL_CONST_P
#define SPECIAL_CONST_P
Old name of RB_SPECIAL_CONST_P.
Definition special_consts.h:56
len
int len
Length of the buffer.
Definition io.h:8
ractor.h
rb_ractor_local_key_t
struct rb_ractor_local_key_struct * rb_ractor_local_key_t
(Opaque) struct that holds a ractor-local storage key.
Definition ractor.h:42
rb_ractor_shareable_p
static bool rb_ractor_shareable_p(VALUE obj)
Queries if multiple Ractors can share the passed object or not.
Definition ractor.h:249
RB_OBJ_SHAREABLE_P
#define RB_OBJ_SHAREABLE_P(obj)
Queries if the passed object has previously classified as shareable or not.
Definition ractor.h:235
ruby.h
ractor_queue
Definition ractor_sync.c:246
rb_id_table
Definition id_table.c:41
rb_ractor_pub
Definition vm_core.h:2330
rb_ractor_struct
Definition ractor_core.h:68
rb_ractor_sync
Definition ractor_core.h:15
rb_thread_sched
Definition thread_none.h:16
st_table
Definition st.h:79
ID
uintptr_t ID
Type that represents a Ruby identifier such as a variable name.
Definition value.h:52
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40