Ruby: ractor_core.h Source File

Ruby 3.4.3p32 (2025-04-14 revision d0b7e5b6a04bde21ca483d20a1546b28b401c2d4)

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
12enum rb_ractor_basket_type {
13 // basket is empty
14 basket_type_none,
15
16 // value is available
17 basket_type_ref,
18 basket_type_copy,
19 basket_type_move,
20 basket_type_will,
21
22 // basket should be deleted
23 basket_type_deleted,
24
25 // basket is reserved
26 basket_type_reserved,
27
28 // take_basket is available
29 basket_type_take_basket,
30
31 // basket is keeping by yielding ractor
32 basket_type_yielding,
33};
34
35// per ractor taking configuration
36 struct rb_ractor_selector_take_config {
37 bool closed;
38 bool oneshot;
39};
40
41 struct rb_ractor_basket {
42 union {
43 enum rb_ractor_basket_type e;
44 rb_atomic_t atomic;
45 } type;
46 VALUE sender;
47
48 union {
49 struct {
50 VALUE v;
51 bool exception;
52 } send;
53
54 struct {
55 struct rb_ractor_basket *basket;
56 struct rb_ractor_selector_take_config *config;
57 } take;
58 } p; // payload
59};
60
61static inline bool
62basket_type_p(struct rb_ractor_basket *b, enum rb_ractor_basket_type type)
63{
64 return b->type.e == type;
65}
66
67static inline bool
68basket_none_p(struct rb_ractor_basket *b)
69{
70 return basket_type_p(b, basket_type_none);
71}
72
73 struct rb_ractor_queue {
74 struct rb_ractor_basket *baskets;
75 int start;
76 int cnt;
77 int size;
78 unsigned int serial;
79 unsigned int reserved_cnt;
80};
81
82enum rb_ractor_wait_status {
83 wait_none = 0x00,
84 wait_receiving = 0x01,
85 wait_taking = 0x02,
86 wait_yielding = 0x04,
87 wait_moving = 0x08,
88};
89
90enum rb_ractor_wakeup_status {
91 wakeup_none,
92 wakeup_by_send,
93 wakeup_by_yield,
94 wakeup_by_take,
95 wakeup_by_close,
96 wakeup_by_interrupt,
97 wakeup_by_retry,
98};
99
100 struct rb_ractor_sync {
101 // ractor lock
102 rb_nativethread_lock_t lock;
103#if RACTOR_CHECK_MODE > 0
104 VALUE locked_by;
105#endif
106
107 bool incoming_port_closed;
108 bool outgoing_port_closed;
109
110 // All sent messages will be pushed into recv_queue
111 struct rb_ractor_queue recv_queue;
112
113 // The following ractors waiting for the yielding by this ractor
114 struct rb_ractor_queue takers_queue;
115
116 // Enabled if the ractor already terminated and not taken yet.
117 struct rb_ractor_basket will_basket;
118
119 struct ractor_wait {
120 enum rb_ractor_wait_status status;
121 enum rb_ractor_wakeup_status wakeup_status;
122 rb_thread_t *waiting_thread;
123 } wait;
124
125#ifndef RUBY_THREAD_PTHREAD_H
126 rb_nativethread_cond_t cond;
127#endif
128};
129
130// created
131// | ready to run
132// ====================== inserted to vm->ractor
133// v
134// blocking <---+ all threads are blocking
135// | |
136// v |
137// running -----+
138// | all threads are terminated.
139// ====================== removed from vm->ractor
140// v
141// terminated
142//
143// status is protected by VM lock (global state)
144enum ractor_status {
145 ractor_created,
146 ractor_running,
147 ractor_blocking,
148 ractor_terminated,
149};
150
151 struct rb_ractor_struct {
152 struct rb_ractor_pub pub;
153
154 struct rb_ractor_sync sync;
155 VALUE receiving_mutex;
156
157 // vm wide barrier synchronization
158 rb_nativethread_cond_t barrier_wait_cond;
159
160 // thread management
161 struct {
162 struct ccan_list_head set;
163 unsigned int cnt;
164 unsigned int blocking_cnt;
165 unsigned int sleeper;
166 struct rb_thread_sched sched;
167 rb_execution_context_t *running_ec;
168 rb_thread_t *main;
169 } threads;
170 VALUE thgroup_default;
171
172 VALUE name;
173 VALUE loc;
174
175 enum ractor_status status_;
176
177 struct ccan_list_node vmlr_node;
178
179 // ractor local data
180
181 st_table *local_storage;
182 struct rb_id_table *idkey_local_storage;
183 VALUE local_storage_store_lock;
184
185 VALUE r_stdin;
186 VALUE r_stdout;
187 VALUE r_stderr;
188 VALUE verbose;
189 VALUE debug;
190
191 void *newobj_cache;
192}; // rb_ractor_t is defined in vm_core.h
193
194
195static inline VALUE
196rb_ractor_self(const rb_ractor_t *r)
197{
198 return r->pub.self;
199}
200
201rb_ractor_t *rb_ractor_main_alloc(void);
202void rb_ractor_main_setup(rb_vm_t *vm, rb_ractor_t *main_ractor, rb_thread_t *main_thread);
203void rb_ractor_atexit(rb_execution_context_t *ec, VALUE result);
204void rb_ractor_atexit_exception(rb_execution_context_t *ec);
205void rb_ractor_teardown(rb_execution_context_t *ec);
206void rb_ractor_receive_parameters(rb_execution_context_t *ec, rb_ractor_t *g, int len, VALUE *ptr);
207void rb_ractor_send_parameters(rb_execution_context_t *ec, rb_ractor_t *g, VALUE args);
208
209 VALUE rb_thread_create_ractor(rb_ractor_t *g, VALUE args, VALUE proc); // defined in thread.c
210
211int rb_ractor_living_thread_num(const rb_ractor_t *);
212 VALUE rb_ractor_thread_list(void);
213bool rb_ractor_p(VALUE rv);
214
215void rb_ractor_living_threads_init(rb_ractor_t *r);
216void rb_ractor_living_threads_insert(rb_ractor_t *r, rb_thread_t *th);
217void rb_ractor_living_threads_remove(rb_ractor_t *r, rb_thread_t *th);
218void rb_ractor_blocking_threads_inc(rb_ractor_t *r, const char *file, int line); // TODO: file, line only for RUBY_DEBUG_LOG
219void rb_ractor_blocking_threads_dec(rb_ractor_t *r, const char *file, int line); // TODO: file, line only for RUBY_DEBUG_LOG
220
221void rb_ractor_vm_barrier_interrupt_running_thread(rb_ractor_t *r);
222void rb_ractor_terminate_interrupt_main_thread(rb_ractor_t *r);
223void rb_ractor_terminate_all(void);
224bool rb_ractor_main_p_(void);
225void rb_ractor_atfork(rb_vm_t *vm, rb_thread_t *th);
226 VALUE rb_ractor_require(VALUE feature);
227 VALUE rb_ractor_autoload_load(VALUE space, ID id);
228
229 VALUE rb_ractor_ensure_shareable(VALUE obj, VALUE name);
230
231RUBY_SYMBOL_EXPORT_BEGIN
232void rb_ractor_finish_marking(void);
233
234bool rb_ractor_shareable_p_continue(VALUE obj);
235
236// THIS FUNCTION SHOULD NOT CALL WHILE INCREMENTAL MARKING!!
237// This function is for T_DATA::free_func
238void rb_ractor_local_storage_delkey(rb_ractor_local_key_t key);
239
240RUBY_SYMBOL_EXPORT_END
241
242static inline bool
243rb_ractor_main_p(void)
244{
245 if (ruby_single_main_ractor) {
246 return true;
247 }
248 else {
249 return rb_ractor_main_p_();
250 }
251}
252
253static inline bool
254rb_ractor_status_p(rb_ractor_t *r, enum ractor_status status)
255{
256 return r->status_ == status;
257}
258
259static inline void
260rb_ractor_sleeper_threads_inc(rb_ractor_t *r)
261{
262 r->threads.sleeper++;
263}
264
265static inline void
266rb_ractor_sleeper_threads_dec(rb_ractor_t *r)
267{
268 r->threads.sleeper--;
269}
270
271static inline void
272rb_ractor_sleeper_threads_clear(rb_ractor_t *r)
273{
274 r->threads.sleeper = 0;
275}
276
277static inline int
278rb_ractor_sleeper_thread_num(rb_ractor_t *r)
279{
280 return r->threads.sleeper;
281}
282
283static inline void
284rb_ractor_thread_switch(rb_ractor_t *cr, rb_thread_t *th)
285{
286 RUBY_DEBUG_LOG("th:%d->%u%s",
287 cr->threads.running_ec ? (int)rb_th_serial(cr->threads.running_ec->thread_ptr) : -1,
288 rb_th_serial(th), cr->threads.running_ec == th->ec ? " (same)" : "");
289
290 if (cr->threads.running_ec != th->ec) {
291 if (0) {
292 ruby_debug_printf("rb_ractor_thread_switch ec:%p->%p\n",
293 (void *)cr->threads.running_ec, (void *)th->ec);
294 }
295 }
296 else {
297 return;
298 }
299
300 if (cr->threads.running_ec != th->ec) {
301 th->running_time_us = 0;
302 }
303
304 cr->threads.running_ec = th->ec;
305
306 VM_ASSERT(cr == GET_RACTOR());
307}
308
309#define rb_ractor_set_current_ec(cr, ec) rb_ractor_set_current_ec_(cr, ec, __FILE__, __LINE__)
310#ifdef RB_THREAD_LOCAL_SPECIFIER
311void rb_current_ec_set(rb_execution_context_t *ec);
312#endif
313
314static inline void
315rb_ractor_set_current_ec_(rb_ractor_t *cr, rb_execution_context_t *ec, const char *file, int line)
316{
317#ifdef RB_THREAD_LOCAL_SPECIFIER
318 rb_current_ec_set(ec);
319#else
320 native_tls_set(ruby_current_ec_key, ec);
321#endif
322 RUBY_DEBUG_LOG2(file, line, "ec:%p->%p", (void *)cr->threads.running_ec, (void *)ec);
323 VM_ASSERT(ec == NULL || cr->threads.running_ec != ec);
324 cr->threads.running_ec = ec;
325}
326
327void rb_vm_ractor_blocking_cnt_inc(rb_vm_t *vm, rb_ractor_t *cr, const char *file, int line);
328void rb_vm_ractor_blocking_cnt_dec(rb_vm_t *vm, rb_ractor_t *cr, const char *file, int line);
329
330static inline uint32_t
331rb_ractor_id(const rb_ractor_t *r)
332{
333 return r->pub.id;
334}
335
336#if RACTOR_CHECK_MODE > 0
337# define RACTOR_BELONGING_ID(obj) (*(uint32_t *)(((uintptr_t)(obj)) + rb_gc_obj_slot_size(obj)))
338
339uint32_t rb_ractor_current_id(void);
340
341static inline void
342rb_ractor_setup_belonging_to(VALUE obj, uint32_t rid)
343{
344 RACTOR_BELONGING_ID(obj) = rid;
345}
346
347static inline uint32_t
348rb_ractor_belonging(VALUE obj)
349{
350 if (SPECIAL_CONST_P(obj) || RB_OBJ_SHAREABLE_P(obj)) {
351 return 0;
352 }
353 else {
354 return RACTOR_BELONGING_ID(obj);
355 }
356}
357
358static inline VALUE
359rb_ractor_confirm_belonging(VALUE obj)
360{
361 uint32_t id = rb_ractor_belonging(obj);
362
363 if (id == 0) {
364 if (UNLIKELY(!rb_ractor_shareable_p(obj))) {
365 rp(obj);
366 rb_bug("id == 0 but not shareable");
367 }
368 }
369 else if (UNLIKELY(id != rb_ractor_current_id())) {
370 if (rb_ractor_shareable_p(obj)) {
371 // ok
372 }
373 else {
374 rp(obj);
375 rb_bug("rb_ractor_confirm_belonging object-ractor id:%u, current-ractor id:%u", id, rb_ractor_current_id());
376 }
377 }
378 return obj;
379}
380#else
381#define rb_ractor_confirm_belonging(obj) obj
382#endif
rb_atomic_t
std::atomic< unsigned > rb_atomic_t
Type that is eligible for atomic operations.
Definition atomic.h:69
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::backward::cxxanyargs::type
VALUE type(ANYARGS)
ANYARGS-ed function type.
Definition cxxanyargs.hpp:56
ruby.h
rb_id_table
Definition id_table.c:41
rb_ractor_basket
Definition ractor_core.h:41
rb_ractor_pub
Definition vm_core.h:2194
rb_ractor_queue
Definition ractor_core.h:73
rb_ractor_selector_take_config
Definition ractor_core.h:36
rb_ractor_struct
Definition ractor_core.h:151
rb_ractor_sync::ractor_wait
Definition ractor_core.h:119
rb_ractor_sync
Definition ractor_core.h:100
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