Ruby 4.1.0dev (2026-11-18 revision 9de06831e37534f8a163e598cc0c6903c7687430)
ractor_core.h (9de06831e37534f8a163e598cc0c6903c7687430)
1#ifndef RUBY_RACTOR_CORE_H
2#define RUBY_RACTOR_CORE_H
3#include "internal/gc.h"
4#include "internal/sanitizers.h"
5#include "ruby/ruby.h"
6#include "ruby/ractor.h"
7#include "vm_core.h"
8#include "id_table.h"
9#include "vm_debug.h"
10#include "hrtime.h"
11
12#ifndef RACTOR_CHECK_MODE
13#define RACTOR_CHECK_MODE (VM_CHECK_MODE || RUBY_DEBUG) && (SIZEOF_UINT64_T == SIZEOF_VALUE)
14#endif
15
16/* Record the registration-time VALUE in each rb_gc_register_address entry so the
17 * verifier can distinguish a transitioned cross-Ractor store from conservative
18 * garbage. Debug and ASAN builds only; production keeps one-word entries. */
19#ifndef RB_GC_REGISTERED_ADDR_CHECK
20# if RUBY_DEBUG || defined(RUBY_ASAN_ENABLED)
21# define RB_GC_REGISTERED_ADDR_CHECK 1
22# else
23# define RB_GC_REGISTERED_ADDR_CHECK 0
24# endif
25#endif
26
27// experimental flag because it is not sure it is the common pattern
28#define RUBY_TYPED_FROZEN_SHAREABLE_NO_REC RUBY_FL_FINALIZE
29
30/* An in-flight move payload, serialized off-heap (defined in ractor.c). */
32
34 // ractor lock
35 rb_nativethread_lock_t lock;
36
37#if RACTOR_CHECK_MODE > 0
38 VALUE locked_by;
39#endif
40
41 // incoming messages
42 struct ractor_queue *recv_queue;
43
44 // waiting threads for receiving
45 struct ccan_list_head waiters;
46
47 // ports
48 VALUE default_port_value;
49 struct st_table *ports;
50 size_t next_port_id;
51
52 // a Ractor::Port kept for internal replies (Qfalse: none yet), busy while one wait uses it
53 VALUE reply_port;
54 bool reply_port_busy;
55
56
57 /* The baskets this Ractor holds that are on no queue: one it is building to send,
58 * and one it has taken off a queue and is materializing. A queued basket is rooted
59 * by its queue instead. Only the owner touches this list. */
60 struct ccan_list_head off_queue_baskets;
61
62 // monitors
63 struct ccan_list_head monitors;
64
65 // value
66 rb_ractor_t *successor;
67 VALUE legacy;
68 bool legacy_exc;
69 bool legacy_taken; /* Ractor#value already returned the value */
70};
71
72struct ractor_basket;
73
74// created
75// | ready to run
76// ====================== inserted to vm->ractor
77// v
78// blocking <---+ all threads are blocking
79// | |
80// v |
81// running -----+
82// | all threads are terminated.
83// ====================== removed from vm->ractor
84// v
85// terminated
86//
87// status is protected by VM lock (global state)
88enum ractor_status {
89 ractor_created,
90 ractor_running,
91 ractor_blocking,
92 ractor_terminated,
93};
94
96 VALUE *addr;
97#if RB_GC_REGISTERED_ADDR_CHECK
98 /* A raw provenance snapshot for verification only. Never mark or dereference it. */
99 VALUE initial_value;
100#endif
101};
102
104 struct rb_ractor_pub pub;
105 struct rb_ractor_sync sync;
106
107 /* rb_gc_register_mark_object pins, per Ractor: the owner marks them (live via
108 * rb_ractor_mark_local_roots, unmerged zombie via the zombie scan) and a merge moves
109 * them to the survivor. Raw malloc, so a merge during sweep cannot re-enter GC. */
110 VALUE *registered_marks;
111 size_t registered_marks_cnt, registered_marks_capa;
112
113 struct rb_ractor_registered_addr *registered_addrs;
114 size_t registered_addrs_cnt, registered_addrs_capa;
115 bool registered_addrs_listed;
116
117 /* traversal-API mark redirect (NULL outside a traversal). Per Ractor so a
118 * concurrent traversal on another Ractor is never observed. A modular GC's
119 * Ractor-less marking worker threads read vm->gc.mark_func_data instead. */
120 struct gc_mark_func_data_struct *mark_func_data;
121
122 // thread management
123 struct {
124 struct ccan_list_head set;
125 unsigned int cnt;
126 unsigned int blocking_cnt;
127 unsigned int sleeper;
128 struct rb_thread_sched sched;
129 rb_execution_context_t *running_ec;
130 rb_thread_t *main;
131 // MN termination epilogue: keeps the dying thread marked (like a set
132 // member) between leaving the living set and its last use
133 rb_thread_t *dying_th;
134
135 // `main` is in rb_thread_terminate_all(), waiting for the others to go
136 bool terminating;
137 } threads;
138
139 /* Postponed jobs targeted at this Ractor
140 * (rb_postponed_job_trigger_for_ractor): bits index the VM-wide
141 * preregistration table; any of this Ractor's threads drains them
142 * in rb_postponed_job_flush. */
143 rb_atomic_t postponed_job_triggered_bits;
144
145 // share requests from other Ractors, a lock-free stack: readers push with CAS, a
146 // thread of this Ractor pops
147 struct class_field_shareable_p *shareable_p_requests;
148
149 VALUE thgroup_default;
150
151 VALUE name;
152 VALUE loc;
153
154 enum ractor_status status_;
155
156 struct ccan_list_node vmlr_node;
157 bool in_terminated_set; /* vmlr_node is on vm->ractor.terminated_set */
158 /* The final self collection ran (ractor_postmortem_collect): from then on
159 * rb_ractor_mark_local_roots roots only the join value and the registered_marks
160 * pins, so the dying thread's own scaffolding can be collected. */
161 bool postmortem;
162
163 // ractor local data
164
165 rb_serial_t next_ec_serial;
166
167 st_table *local_storage;
168 struct rb_id_table *idkey_local_storage;
169 VALUE local_storage_store_lock;
170
171 /* 0 until first use: rb_ractor_stdin and friends build them lazily, with plain
172 * stores (rooted via ractor_mark_unshareable_parts; a write barrier on the
173 * shareable wrapper would shref-pin them). */
174 VALUE r_stdin;
175 VALUE r_stdout;
176 VALUE r_stderr;
177 VALUE verbose;
178 VALUE debug;
179
180 bool malloc_gc_disabled;
181 bool main_ractor;
182 void *newobj_cache;
183
184 /* This Ractor's objspace. The main Ractor receives the boot objspace from
185 * rb_gc_init_objspaces; a non-main Ractor shares the main one until it gets its
186 * own (while this is NULL). */
187 void *objspace;
188
189 /* A child Ractor's objspace is populated (Thread/Fiber wrappers) before it joins
190 * vm->ractor.set, so a whole-VM walk would miss it. Park it here from wrapper
191 * allocation until vm_insert_ractor clears it (under the VM lock) so the global GC
192 * still enumerates it. */
193 void *creating_child_objspace;
194
195}; // rb_ractor_t is defined in vm_core.h
196
197/* Mark the GC roots held in Ractor r's C structs (from the root scan in gc.c). */
198struct rb_gc_mark_ctx;
199void rb_ractor_mark_local_roots(const struct rb_gc_mark_ctx *ctx, rb_ractor_t *r);
200void rb_ractor_mark_shareable_p_inflight(const struct rb_gc_mark_ctx *ctx);
201void rb_ractor_mark_terminated_join_value(rb_ractor_t *r);
202void rb_ractor_reap_dead_ports(rb_ractor_t *r);
203
204/* Move src's registered_marks to dst and leave src empty (on join or when an orphan
205 * is absorbed). An absorb can run during a GC sweep, so the implementation uses raw
206 * realloc (ractor.c). */
207void rb_ractor_absorb_registered_marks(rb_ractor_t *dst, rb_ractor_t *src);
208
209void rb_ractor_absorb_registered_addrs_without_gc(rb_ractor_t *dst, rb_ractor_t *src);
210
211enum ractor_wakeup_status {
212 wakeup_none,
213 wakeup_by_send,
214 wakeup_by_interrupt,
215 wakeup_by_close,
216};
217
219 enum ractor_wakeup_status wakeup_status;
220 rb_thread_t *th;
221 struct ccan_list_node node;
222 rb_atomic_t event_serial;
223
224 // absolute deadline for this wait, NULL when there is no timeout
225 const rb_hrtime_t *end;
226};
227
228static inline VALUE
229rb_ractor_self(const rb_ractor_t *r)
230{
231 return r->pub.self;
232}
233
234rb_ractor_t *rb_ractor_main_alloc(void);
235void rb_ractor_main_setup(rb_vm_t *vm, rb_ractor_t *main_ractor, rb_thread_t *main_thread);
236void rb_ractor_atexit(rb_execution_context_t *ec, VALUE result);
237void rb_ractor_atexit_exception(rb_execution_context_t *ec);
238void rb_ractor_teardown(rb_execution_context_t *ec);
239void rb_ractor_receive_parameters(rb_execution_context_t *ec, rb_ractor_t *g, int len, VALUE *ptr);
240void rb_ractor_send_parameters(rb_execution_context_t *ec, rb_ractor_t *g, VALUE args);
241void rb_ractor_setup_default_port(rb_ractor_t *r);
242
243VALUE rb_thread_create_ractor(rb_ractor_t *g, VALUE args, VALUE proc); // defined in thread.c
244
245int rb_ractor_living_thread_num(const rb_ractor_t *);
246VALUE rb_ractor_thread_list(void);
247bool rb_ractor_p(VALUE rv);
248
249void rb_ractor_living_threads_init(rb_ractor_t *r);
250void rb_ractor_living_threads_insert(rb_ractor_t *r, rb_thread_t *th);
251void rb_ractor_living_threads_remove(rb_ractor_t *r, rb_thread_t *th);
252
253/* The structs the final self collection swept while the dying thread still stood on
254 * them; that thread frees them at its very last step (rb_ractor_postmortem_free). */
256 struct rb_thread_struct *th;
257 struct rb_fiber_struct *fiber;
258};
259void rb_ractor_postmortem(rb_thread_t *th, struct rb_ractor_postmortem_frees *pf);
260void rb_ractor_postmortem_free(const struct rb_ractor_postmortem_frees *pf);
261void rb_ractor_cancel_creation(rb_ractor_t *r, rb_thread_t *th);
262void rb_ractor_blocking_threads_inc(rb_ractor_t *r, const char *file, int line); // TODO: file, line only for RUBY_DEBUG_LOG
263void rb_ractor_blocking_threads_dec(rb_ractor_t *r, const char *file, int line); // TODO: file, line only for RUBY_DEBUG_LOG
264
265void rb_ractor_vm_barrier_interrupt_running_thread(rb_ractor_t *r);
266void rb_ractor_terminate_interrupt_main_thread(rb_ractor_t *r);
267void rb_ractor_terminate_all(void);
268bool rb_ractor_main_p_(void);
269void rb_ractor_atfork(rb_vm_t *vm, rb_thread_t *th);
270void rb_ractor_terminate_atfork(rb_vm_t *vm, rb_ractor_t *th);
271VALUE rb_ractor_require(VALUE feature, bool silent);
272VALUE rb_ractor_autoload_load(VALUE space, ID id);
273
274VALUE rb_ractor_ensure_shareable(VALUE obj, VALUE name);
275st_table *rb_ractor_targeted_hooks(rb_ractor_t *cr);
276
277RUBY_SYMBOL_EXPORT_BEGIN
278void rb_ractor_finish_marking(bool full_mark);
279
280bool rb_ractor_shareable_p_continue(VALUE obj);
281
282// THIS FUNCTION SHOULD NOT CALL WHILE INCREMENTAL MARKING!!
283// This function is for T_DATA::free_func
284void rb_ractor_local_storage_delkey(rb_ractor_local_key_t key);
285
286RUBY_SYMBOL_EXPORT_END
287
288static inline bool
289rb_ractor_main_p(void)
290{
291 if (ruby_single_main_ractor) {
292 return true;
293 }
294 else {
295 return rb_ractor_main_p_();
296 }
297}
298
299static inline bool
300rb_ractor_status_p(rb_ractor_t *r, enum ractor_status status)
301{
302 return r->status_ == status;
303}
304
305static inline void
306rb_ractor_sleeper_threads_inc(rb_ractor_t *r)
307{
308 r->threads.sleeper++;
309}
310
311static inline void
312rb_ractor_sleeper_threads_dec(rb_ractor_t *r)
313{
314 r->threads.sleeper--;
315}
316
317static inline void
318rb_ractor_sleeper_threads_clear(rb_ractor_t *r)
319{
320 r->threads.sleeper = 0;
321}
322
323static inline int
324rb_ractor_sleeper_thread_num(rb_ractor_t *r)
325{
326 return r->threads.sleeper;
327}
328
329static inline void
330rb_ractor_thread_switch(rb_ractor_t *cr, rb_thread_t *th, bool always_reset)
331{
332 RUBY_DEBUG_LOG("th:%d->%u%s",
333 cr->threads.running_ec ? (int)rb_th_serial(cr->threads.running_ec->thread_ptr) : -1,
334 rb_th_serial(th), cr->threads.running_ec == th->ec ? " (same)" : "");
335
336 if (cr->threads.running_ec != th->ec || always_reset) {
337 th->running_time_us = 0;
338 }
339
340 if (cr->threads.running_ec != th->ec) {
341 if (0) {
342 ruby_debug_printf("rb_ractor_thread_switch ec:%p->%p\n",
343 (void *)cr->threads.running_ec, (void *)th->ec);
344 }
345 }
346 // seq_cst even if rb_ractor_set_current_ec stored it already, then read the bits:
347 // a trigger either sees th->ec or its bit is seen here
348 RUBY_ATOMIC_PTR_SET(cr->threads.running_ec, th->ec);
349
350 // a job for this Ractor may have flagged a thread that went to sleep since
351 if (RUBY_ATOMIC_LOAD(cr->postponed_job_triggered_bits)) {
352 RUBY_VM_SET_POSTPONED_JOB_INTERRUPT(th->ec);
353 }
354
355 VM_ASSERT(cr == GET_RACTOR());
356}
357
358#define rb_ractor_set_current_ec(cr, ec) rb_ractor_set_current_ec_(cr, ec, __FILE__, __LINE__)
359#ifdef RB_THREAD_LOCAL_SPECIFIER
360void rb_current_ec_set(rb_execution_context_t *ec);
361#endif
362
363static inline void
364rb_ractor_set_current_ec_(rb_ractor_t *cr, rb_execution_context_t *ec, const char *file, int line)
365{
366#ifdef RB_THREAD_LOCAL_SPECIFIER
367 rb_current_ec_set(ec);
368#else
369 native_tls_set(ruby_current_ec_key, ec);
370#endif
371 RUBY_DEBUG_LOG2(file, line, "ec:%p->%p", (void *)cr->threads.running_ec, (void *)ec);
372 VM_ASSERT(ec == NULL || cr->threads.running_ec != ec);
373 RUBY_ATOMIC_PTR_SET(cr->threads.running_ec, ec); // read by other Ractors' triggers
374}
375
376void rb_vm_ractor_blocking_cnt_inc(rb_vm_t *vm, rb_ractor_t *cr, const char *file, int line);
377void rb_vm_ractor_blocking_cnt_dec(rb_vm_t *vm, rb_ractor_t *cr, const char *file, int line);
378
379static inline rb_serial_t
380rb_ractor_id(const rb_ractor_t *r)
381{
382 return r->pub.id;
383}
384
385static inline void
386rb_ractor_targeted_hooks_incr(rb_ractor_t *cr)
387{
388 cr->pub.targeted_hooks_cnt++;
389}
390
391static inline void
392rb_ractor_targeted_hooks_decr(rb_ractor_t *cr)
393{
394 RUBY_ASSERT(cr->pub.targeted_hooks_cnt > 0);
395 cr->pub.targeted_hooks_cnt--;
396}
397
398static inline unsigned int
399rb_ractor_targeted_hooks_cnt(rb_ractor_t *cr)
400{
401 return cr->pub.targeted_hooks_cnt;
402}
403
404#if RACTOR_CHECK_MODE > 0
405
406extern bool rb_ractor_ignore_belonging_flag;
407
408/* An object's owning Ractor is decided by the objspace its page belongs to
409 * (rb_gc_obj_foreign_p). Putting an unshareable object on the VM stack of anyone
410 * but its owner is a containment violation. */
411static inline VALUE
412rb_ractor_confirm_belonging(VALUE obj)
413{
414 if (rb_ractor_ignore_belonging_flag) return obj;
415 if (SPECIAL_CONST_P(obj) || RB_OBJ_SHAREABLE_P(obj)) return obj;
416
417 if (UNLIKELY(rb_gc_obj_foreign_p(obj))) {
418 rp(obj);
419 rb_bug("rb_ractor_confirm_belonging: unshareable object of another Ractor's objspace");
420 }
421 return obj;
422}
423
424static inline void
425rb_ractor_ignore_belonging(bool flag)
426{
427 rb_ractor_ignore_belonging_flag = flag;
428}
429
430#else
431#define rb_ractor_confirm_belonging(obj) obj
432#define rb_ractor_ignore_belonging(flag) (0)
433#endif
434
435#endif /* RUBY_RACTOR_CORE_H */
std::atomic< unsigned > rb_atomic_t
Type that is eligible for atomic operations.
Definition atomic.h:69
#define RUBY_ATOMIC_LOAD(var)
Atomic load.
Definition atomic.h:175
#define RUBY_ATOMIC_PTR_SET(var, val)
Identical to RUBY_ATOMIC_SET, except it expects its arguments are void*.
Definition atomic.h:361
#define SPECIAL_CONST_P
Old name of RB_SPECIAL_CONST_P.
#define RUBY_ASSERT(...)
Asserts that the given expression is truthy if and only if RUBY_DEBUG is truthy.
Definition assert.h:219
int len
Length of the buffer.
Definition io.h:8
struct rb_ractor_local_key_struct * rb_ractor_local_key_t
(Opaque) struct that holds a ractor-local storage key.
Definition ractor.h:42
#define RB_OBJ_SHAREABLE_P(obj)
Queries if the passed object has previously classified as shareable or not.
Definition ractor.h:255
Definition st.h:79
uintptr_t ID
Type that represents a Ruby identifier such as a variable name.
Definition value.h:52
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40