Ruby: scheduler.c Source File

Ruby 3.4.8p72 (2025-12-17 revision 995b59f66677d44767ce9faac6957e5543617ff9)

scheduler.c
1/**********************************************************************
2
3 scheduler.c
4
5 $Author$
6
7 Copyright (C) 2020 Samuel Grant Dawson Williams
8
9**********************************************************************/
10
11#include "vm_core.h"
12#include "eval_intern.h"
13#include "ruby/fiber/scheduler.h"
14#include "ruby/io.h"
15#include "ruby/io/buffer.h"
16
17#include "ruby/thread.h"
18
19// For `ruby_thread_has_gvl_p`.
20#include "internal/thread.h"
21
22static ID id_close;
23static ID id_scheduler_close;
24
25static ID id_block;
26static ID id_unblock;
27
28static ID id_timeout_after;
29static ID id_kernel_sleep;
30static ID id_process_wait;
31
32static ID id_io_read, id_io_pread;
33static ID id_io_write, id_io_pwrite;
34static ID id_io_wait;
35static ID id_io_select;
36static ID id_io_close;
37
38static ID id_address_resolve;
39
40static ID id_blocking_operation_wait;
41
42static ID id_fiber_schedule;
43
44/*
45 * Document-class: Fiber::Scheduler
46 *
47 * This is not an existing class, but documentation of the interface that Scheduler
48 * object should comply to in order to be used as argument to Fiber.scheduler and handle non-blocking
49 * fibers. See also the "Non-blocking fibers" section in Fiber class docs for explanations
50 * of some concepts.
51 *
52 * Scheduler's behavior and usage are expected to be as follows:
53 *
54 * * When the execution in the non-blocking Fiber reaches some blocking operation (like
55 * sleep, wait for a process, or a non-ready I/O), it calls some of the scheduler's
56 * hook methods, listed below.
57 * * Scheduler somehow registers what the current fiber is waiting on, and yields control
58 * to other fibers with Fiber.yield (so the fiber would be suspended while expecting its
59 * wait to end, and other fibers in the same thread can perform)
60 * * At the end of the current thread execution, the scheduler's method #scheduler_close is called
61 * * The scheduler runs into a wait loop, checking all the blocked fibers (which it has
62 * registered on hook calls) and resuming them when the awaited resource is ready
63 * (e.g. I/O ready or sleep time elapsed).
64 *
65 * This way concurrent execution will be achieved transparently for every
66 * individual Fiber's code.
67 *
68 * Scheduler implementations are provided by gems, like
69 * Async[https://github.com/socketry/async].
70 *
71 * Hook methods are:
72 *
73 * * #io_wait, #io_read, #io_write, #io_pread, #io_pwrite, and #io_select, #io_close
74 * * #process_wait
75 * * #kernel_sleep
76 * * #timeout_after
77 * * #address_resolve
78 * * #block and #unblock
79 * * #blocking_operation_wait
80 * * (the list is expanded as Ruby developers make more methods having non-blocking calls)
81 *
82 * When not specified otherwise, the hook implementations are mandatory: if they are not
83 * implemented, the methods trying to call hook will fail. To provide backward compatibility,
84 * in the future hooks will be optional (if they are not implemented, due to the scheduler
85 * being created for the older Ruby version, the code which needs this hook will not fail,
86 * and will just behave in a blocking fashion).
87 *
88 * It is also strongly recommended that the scheduler implements the #fiber method, which is
89 * delegated to by Fiber.schedule.
90 *
91 * Sample _toy_ implementation of the scheduler can be found in Ruby's code, in
92 * <tt>test/fiber/scheduler.rb</tt>
93 *
94 */
95void
96Init_Fiber_Scheduler(void)
97{
98 id_close = rb_intern_const("close");
99 id_scheduler_close = rb_intern_const("scheduler_close");
100
101 id_block = rb_intern_const("block");
102 id_unblock = rb_intern_const("unblock");
103
104 id_timeout_after = rb_intern_const("timeout_after");
105 id_kernel_sleep = rb_intern_const("kernel_sleep");
106 id_process_wait = rb_intern_const("process_wait");
107
108 id_io_read = rb_intern_const("io_read");
109 id_io_pread = rb_intern_const("io_pread");
110 id_io_write = rb_intern_const("io_write");
111 id_io_pwrite = rb_intern_const("io_pwrite");
112
113 id_io_wait = rb_intern_const("io_wait");
114 id_io_select = rb_intern_const("io_select");
115 id_io_close = rb_intern_const("io_close");
116
117 id_address_resolve = rb_intern_const("address_resolve");
118
119 id_blocking_operation_wait = rb_intern_const("blocking_operation_wait");
120
121 id_fiber_schedule = rb_intern_const("fiber");
122
123#if 0 /* for RDoc */
124 rb_cFiberScheduler = rb_define_class_under(rb_cFiber, "Scheduler", rb_cObject);
125 rb_define_method(rb_cFiberScheduler, "close", rb_fiber_scheduler_close, 0);
126 rb_define_method(rb_cFiberScheduler, "process_wait", rb_fiber_scheduler_process_wait, 2);
127 rb_define_method(rb_cFiberScheduler, "io_wait", rb_fiber_scheduler_io_wait, 3);
128 rb_define_method(rb_cFiberScheduler, "io_read", rb_fiber_scheduler_io_read, 4);
129 rb_define_method(rb_cFiberScheduler, "io_write", rb_fiber_scheduler_io_write, 4);
130 rb_define_method(rb_cFiberScheduler, "io_pread", rb_fiber_scheduler_io_pread, 5);
131 rb_define_method(rb_cFiberScheduler, "io_pwrite", rb_fiber_scheduler_io_pwrite, 5);
132 rb_define_method(rb_cFiberScheduler, "io_select", rb_fiber_scheduler_io_select, 4);
133 rb_define_method(rb_cFiberScheduler, "kernel_sleep", rb_fiber_scheduler_kernel_sleep, 1);
134 rb_define_method(rb_cFiberScheduler, "address_resolve", rb_fiber_scheduler_address_resolve, 1);
135 rb_define_method(rb_cFiberScheduler, "timeout_after", rb_fiber_scheduler_timeout_after, 3);
136 rb_define_method(rb_cFiberScheduler, "block", rb_fiber_scheduler_block, 2);
137 rb_define_method(rb_cFiberScheduler, "unblock", rb_fiber_scheduler_unblock, 2);
138 rb_define_method(rb_cFiberScheduler, "fiber", rb_fiber_scheduler, -2);
139 rb_define_method(rb_cFiberScheduler, "blocking_operation_wait", rb_fiber_scheduler_blocking_operation_wait, -2);
140#endif
141}
142
143 VALUE
144rb_fiber_scheduler_get(void)
145{
146 RUBY_ASSERT(ruby_thread_has_gvl_p());
147
148 rb_thread_t *thread = GET_THREAD();
149 RUBY_ASSERT(thread);
150
151 return thread->scheduler;
152}
153
154static void
155verify_interface(VALUE scheduler)
156{
157 if (!rb_respond_to(scheduler, id_block)) {
158 rb_raise(rb_eArgError, "Scheduler must implement #block");
159 }
160
161 if (!rb_respond_to(scheduler, id_unblock)) {
162 rb_raise(rb_eArgError, "Scheduler must implement #unblock");
163 }
164
165 if (!rb_respond_to(scheduler, id_kernel_sleep)) {
166 rb_raise(rb_eArgError, "Scheduler must implement #kernel_sleep");
167 }
168
169 if (!rb_respond_to(scheduler, id_io_wait)) {
170 rb_raise(rb_eArgError, "Scheduler must implement #io_wait");
171 }
172}
173
174static VALUE
175fiber_scheduler_close(VALUE scheduler)
176{
177 return rb_fiber_scheduler_close(scheduler);
178}
179
180static VALUE
181fiber_scheduler_close_ensure(VALUE _thread)
182{
183 rb_thread_t *thread = (rb_thread_t*)_thread;
184 thread->scheduler = Qnil;
185
186 return Qnil;
187}
188
189 VALUE
190rb_fiber_scheduler_set(VALUE scheduler)
191{
192 RUBY_ASSERT(ruby_thread_has_gvl_p());
193
194 rb_thread_t *thread = GET_THREAD();
195 RUBY_ASSERT(thread);
196
197 if (scheduler != Qnil) {
198 verify_interface(scheduler);
199 }
200
201 // We invoke Scheduler#close when setting it to something else, to ensure
202 // the previous scheduler runs to completion before changing the scheduler.
203 // That way, we do not need to consider interactions, e.g., of a Fiber from
204 // the previous scheduler with the new scheduler.
205 if (thread->scheduler != Qnil) {
206 // rb_fiber_scheduler_close(thread->scheduler);
207 rb_ensure(fiber_scheduler_close, thread->scheduler, fiber_scheduler_close_ensure, (VALUE)thread);
208 }
209
210 thread->scheduler = scheduler;
211
212 return thread->scheduler;
213}
214
215static VALUE
216rb_fiber_scheduler_current_for_threadptr(rb_thread_t *thread)
217{
218 RUBY_ASSERT(thread);
219
220 if (thread->blocking == 0) {
221 return thread->scheduler;
222 }
223 else {
224 return Qnil;
225 }
226}
227
228 VALUE
229rb_fiber_scheduler_current(void)
230{
231 return rb_fiber_scheduler_current_for_threadptr(GET_THREAD());
232}
233
234 VALUE rb_fiber_scheduler_current_for_thread(VALUE thread)
235{
236 return rb_fiber_scheduler_current_for_threadptr(rb_thread_ptr(thread));
237}
238
239/*
240 *
241 * Document-method: Fiber::Scheduler#close
242 *
243 * Called when the current thread exits. The scheduler is expected to implement this
244 * method in order to allow all waiting fibers to finalize their execution.
245 *
246 * The suggested pattern is to implement the main event loop in the #close method.
247 *
248 */
249 VALUE
250rb_fiber_scheduler_close(VALUE scheduler)
251{
252 RUBY_ASSERT(ruby_thread_has_gvl_p());
253
254 VALUE result;
255
256 // The reason for calling `scheduler_close` before calling `close` is for
257 // legacy schedulers which implement `close` and expect the user to call
258 // it. Subsequently, that method would call `Fiber.set_scheduler(nil)`
259 // which should call `scheduler_close`. If it were to call `close`, it
260 // would create an infinite loop.
261
262 result = rb_check_funcall(scheduler, id_scheduler_close, 0, NULL);
263 if (!UNDEF_P(result)) return result;
264
265 result = rb_check_funcall(scheduler, id_close, 0, NULL);
266 if (!UNDEF_P(result)) return result;
267
268 return Qnil;
269}
270
271 VALUE
272rb_fiber_scheduler_make_timeout(struct timeval *timeout)
273{
274 if (timeout) {
275 return rb_float_new((double)timeout->tv_sec + (0.000001f * timeout->tv_usec));
276 }
277
278 return Qnil;
279}
280
281/*
282 * Document-method: Fiber::Scheduler#kernel_sleep
283 * call-seq: kernel_sleep(duration = nil)
284 *
285 * Invoked by Kernel#sleep and Mutex#sleep and is expected to provide
286 * an implementation of sleeping in a non-blocking way. Implementation might
287 * register the current fiber in some list of "which fiber wait until what
288 * moment", call Fiber.yield to pass control, and then in #close resume
289 * the fibers whose wait period has elapsed.
290 *
291 */
292 VALUE
293rb_fiber_scheduler_kernel_sleep(VALUE scheduler, VALUE timeout)
294{
295 return rb_funcall(scheduler, id_kernel_sleep, 1, timeout);
296}
297
298 VALUE
299rb_fiber_scheduler_kernel_sleepv(VALUE scheduler, int argc, VALUE * argv)
300{
301 return rb_funcallv(scheduler, id_kernel_sleep, argc, argv);
302}
303
304#if 0
305/*
306 * Document-method: Fiber::Scheduler#timeout_after
307 * call-seq: timeout_after(duration, exception_class, *exception_arguments, &block) -> result of block
308 *
309 * Invoked by Timeout.timeout to execute the given +block+ within the given
310 * +duration+. It can also be invoked directly by the scheduler or user code.
311 *
312 * Attempt to limit the execution time of a given +block+ to the given
313 * +duration+ if possible. When a non-blocking operation causes the +block+'s
314 * execution time to exceed the specified +duration+, that non-blocking
315 * operation should be interrupted by raising the specified +exception_class+
316 * constructed with the given +exception_arguments+.
317 *
318 * General execution timeouts are often considered risky. This implementation
319 * will only interrupt non-blocking operations. This is by design because it's
320 * expected that non-blocking operations can fail for a variety of
321 * unpredictable reasons, so applications should already be robust in handling
322 * these conditions and by implication timeouts.
323 *
324 * However, as a result of this design, if the +block+ does not invoke any
325 * non-blocking operations, it will be impossible to interrupt it. If you
326 * desire to provide predictable points for timeouts, consider adding
327 * +sleep(0)+.
328 *
329 * If the block is executed successfully, its result will be returned.
330 *
331 * The exception will typically be raised using Fiber#raise.
332 */
333 VALUE
334rb_fiber_scheduler_timeout_after(VALUE scheduler, VALUE timeout, VALUE exception, VALUE message)
335{
336 VALUE arguments[] = {
337 timeout, exception, message
338 };
339
340 return rb_check_funcall(scheduler, id_timeout_after, 3, arguments);
341}
342
343 VALUE
344rb_fiber_scheduler_timeout_afterv(VALUE scheduler, int argc, VALUE * argv)
345{
346 return rb_check_funcall(scheduler, id_timeout_after, argc, argv);
347}
348#endif
349
350/*
351 * Document-method: Fiber::Scheduler#process_wait
352 * call-seq: process_wait(pid, flags)
353 *
354 * Invoked by Process::Status.wait in order to wait for a specified process.
355 * See that method description for arguments description.
356 *
357 * Suggested minimal implementation:
358 *
359 * Thread.new do
360 * Process::Status.wait(pid, flags)
361 * end.value
362 *
363 * This hook is optional: if it is not present in the current scheduler,
364 * Process::Status.wait will behave as a blocking method.
365 *
366 * Expected to return a Process::Status instance.
367 */
368 VALUE
369rb_fiber_scheduler_process_wait(VALUE scheduler, rb_pid_t pid, int flags)
370{
371 VALUE arguments[] = {
372 PIDT2NUM(pid), RB_INT2NUM(flags)
373 };
374
375 return rb_check_funcall(scheduler, id_process_wait, 2, arguments);
376}
377
378/*
379 * Document-method: Fiber::Scheduler#block
380 * call-seq: block(blocker, timeout = nil)
381 *
382 * Invoked by methods like Thread.join, and by Mutex, to signify that current
383 * Fiber is blocked until further notice (e.g. #unblock) or until +timeout+ has
384 * elapsed.
385 *
386 * +blocker+ is what we are waiting on, informational only (for debugging and
387 * logging). There are no guarantee about its value.
388 *
389 * Expected to return boolean, specifying whether the blocking operation was
390 * successful or not.
391 */
392 VALUE
393rb_fiber_scheduler_block(VALUE scheduler, VALUE blocker, VALUE timeout)
394{
395 return rb_funcall(scheduler, id_block, 2, blocker, timeout);
396}
397
398/*
399 * Document-method: Fiber::Scheduler#unblock
400 * call-seq: unblock(blocker, fiber)
401 *
402 * Invoked to wake up Fiber previously blocked with #block (for example, Mutex#lock
403 * calls #block and Mutex#unlock calls #unblock). The scheduler should use
404 * the +fiber+ parameter to understand which fiber is unblocked.
405 *
406 * +blocker+ is what was awaited for, but it is informational only (for debugging
407 * and logging), and it is not guaranteed to be the same value as the +blocker+ for
408 * #block.
409 *
410 */
411 VALUE
412rb_fiber_scheduler_unblock(VALUE scheduler, VALUE blocker, VALUE fiber)
413{
414 RUBY_ASSERT(rb_obj_is_fiber(fiber));
415
416 VALUE result;
417 enum ruby_tag_type state;
418
419 // `rb_fiber_scheduler_unblock` can be called from points where `errno` is expected to be preserved. Therefore, we should save and restore it. For example `io_binwrite` calls `rb_fiber_scheduler_unblock` and if `errno` is reset to 0 by user code, it will break the error handling in `io_write`.
420 //
421 // If we explicitly preserve `errno` in `io_binwrite` and other similar functions (e.g. by returning it), this code is no longer needed. I hope in the future we will be able to remove it.
422 int saved_errno = errno;
423
424 // We must prevent interrupts while invoking the unblock method, because otherwise fibers can be left permanently blocked if an interrupt occurs during the execution of user code.
425 rb_execution_context_t *ec = GET_EC();
426 int saved_interrupt_mask = ec->interrupt_mask;
427 ec->interrupt_mask |= PENDING_INTERRUPT_MASK;
428
429 EC_PUSH_TAG(ec);
430 if ((state = EC_EXEC_TAG()) == TAG_NONE) {
431 result = rb_funcall(scheduler, id_unblock, 2, blocker, fiber);
432 }
433 EC_POP_TAG();
434
435 ec->interrupt_mask = saved_interrupt_mask;
436
437 if (state) {
438 EC_JUMP_TAG(ec, state);
439 }
440
441 RUBY_VM_CHECK_INTS(ec);
442
443 errno = saved_errno;
444
445 return result;
446}
447
448/*
449 * Document-method: Fiber::Scheduler#io_wait
450 * call-seq: io_wait(io, events, timeout)
451 *
452 * Invoked by IO#wait, IO#wait_readable, IO#wait_writable to ask whether the
453 * specified descriptor is ready for specified events within
454 * the specified +timeout+.
455 *
456 * +events+ is a bit mask of <tt>IO::READABLE</tt>, <tt>IO::WRITABLE</tt>, and
457 * <tt>IO::PRIORITY</tt>.
458 *
459 * Suggested implementation should register which Fiber is waiting for which
460 * resources and immediately calling Fiber.yield to pass control to other
461 * fibers. Then, in the #close method, the scheduler might dispatch all the
462 * I/O resources to fibers waiting for it.
463 *
464 * Expected to return the subset of events that are ready immediately.
465 *
466 */
467 VALUE
468rb_fiber_scheduler_io_wait(VALUE scheduler, VALUE io, VALUE events, VALUE timeout)
469{
470 return rb_funcall(scheduler, id_io_wait, 3, io, events, timeout);
471}
472
473 VALUE
474rb_fiber_scheduler_io_wait_readable(VALUE scheduler, VALUE io)
475{
476 return rb_fiber_scheduler_io_wait(scheduler, io, RB_UINT2NUM(RUBY_IO_READABLE), rb_io_timeout(io));
477}
478
479 VALUE
480rb_fiber_scheduler_io_wait_writable(VALUE scheduler, VALUE io)
481{
482 return rb_fiber_scheduler_io_wait(scheduler, io, RB_UINT2NUM(RUBY_IO_WRITABLE), rb_io_timeout(io));
483}
484
485/*
486 * Document-method: Fiber::Scheduler#io_select
487 * call-seq: io_select(readables, writables, exceptables, timeout)
488 *
489 * Invoked by IO.select to ask whether the specified descriptors are ready for
490 * specified events within the specified +timeout+.
491 *
492 * Expected to return the 3-tuple of Array of IOs that are ready.
493 *
494 */
495 VALUE rb_fiber_scheduler_io_select(VALUE scheduler, VALUE readables, VALUE writables, VALUE exceptables, VALUE timeout)
496{
497 VALUE arguments[] = {
498 readables, writables, exceptables, timeout
499 };
500
501 return rb_fiber_scheduler_io_selectv(scheduler, 4, arguments);
502}
503
504 VALUE rb_fiber_scheduler_io_selectv(VALUE scheduler, int argc, VALUE *argv)
505{
506 // I wondered about extracting argv, and checking if there is only a single
507 // IO instance, and instead calling `io_wait`. However, it would require a
508 // decent amount of work and it would be hard to preserve the exact
509 // semantics of IO.select.
510
511 return rb_check_funcall(scheduler, id_io_select, argc, argv);
512}
513
514/*
515 * Document-method: Fiber::Scheduler#io_read
516 * call-seq: io_read(io, buffer, length, offset) -> read length or -errno
517 *
518 * Invoked by IO#read or IO#Buffer.read to read +length+ bytes from +io+ into a
519 * specified +buffer+ (see IO::Buffer) at the given +offset+.
520 *
521 * The +length+ argument is the "minimum length to be read". If the IO buffer
522 * size is 8KiB, but the +length+ is +1024+ (1KiB), up to 8KiB might be read,
523 * but at least 1KiB will be. Generally, the only case where less data than
524 * +length+ will be read is if there is an error reading the data.
525 *
526 * Specifying a +length+ of 0 is valid and means try reading at least once and
527 * return any available data.
528 *
529 * Suggested implementation should try to read from +io+ in a non-blocking
530 * manner and call #io_wait if the +io+ is not ready (which will yield control
531 * to other fibers).
532 *
533 * See IO::Buffer for an interface available to return data.
534 *
535 * Expected to return number of bytes read, or, in case of an error,
536 * <tt>-errno</tt> (negated number corresponding to system's error code).
537 *
538 * The method should be considered _experimental_.
539 */
540 VALUE
541rb_fiber_scheduler_io_read(VALUE scheduler, VALUE io, VALUE buffer, size_t length, size_t offset)
542{
543 VALUE arguments[] = {
544 io, buffer, SIZET2NUM(length), SIZET2NUM(offset)
545 };
546
547 return rb_check_funcall(scheduler, id_io_read, 4, arguments);
548}
549
550/*
551 * Document-method: Fiber::Scheduler#io_read
552 * call-seq: io_pread(io, buffer, from, length, offset) -> read length or -errno
553 *
554 * Invoked by IO#pread or IO::Buffer#pread to read +length+ bytes from +io+
555 * at offset +from+ into a specified +buffer+ (see IO::Buffer) at the given
556 * +offset+.
557 *
558 * This method is semantically the same as #io_read, but it allows to specify
559 * the offset to read from and is often better for asynchronous IO on the same
560 * file.
561 *
562 * The method should be considered _experimental_.
563 */
564 VALUE
565rb_fiber_scheduler_io_pread(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t length, size_t offset)
566{
567 VALUE arguments[] = {
568 io, buffer, OFFT2NUM(from), SIZET2NUM(length), SIZET2NUM(offset)
569 };
570
571 return rb_check_funcall(scheduler, id_io_pread, 5, arguments);
572}
573
574/*
575 * Document-method: Scheduler#io_write
576 * call-seq: io_write(io, buffer, length, offset) -> written length or -errno
577 *
578 * Invoked by IO#write or IO::Buffer#write to write +length+ bytes to +io+ from
579 * from a specified +buffer+ (see IO::Buffer) at the given +offset+.
580 *
581 * The +length+ argument is the "minimum length to be written". If the IO
582 * buffer size is 8KiB, but the +length+ specified is 1024 (1KiB), at most 8KiB
583 * will be written, but at least 1KiB will be. Generally, the only case where
584 * less data than +length+ will be written is if there is an error writing the
585 * data.
586 *
587 * Specifying a +length+ of 0 is valid and means try writing at least once, as
588 * much data as possible.
589 *
590 * Suggested implementation should try to write to +io+ in a non-blocking
591 * manner and call #io_wait if the +io+ is not ready (which will yield control
592 * to other fibers).
593 *
594 * See IO::Buffer for an interface available to get data from buffer
595 * efficiently.
596 *
597 * Expected to return number of bytes written, or, in case of an error,
598 * <tt>-errno</tt> (negated number corresponding to system's error code).
599 *
600 * The method should be considered _experimental_.
601 */
602 VALUE
603rb_fiber_scheduler_io_write(VALUE scheduler, VALUE io, VALUE buffer, size_t length, size_t offset)
604{
605 VALUE arguments[] = {
606 io, buffer, SIZET2NUM(length), SIZET2NUM(offset)
607 };
608
609 return rb_check_funcall(scheduler, id_io_write, 4, arguments);
610}
611
612/*
613 * Document-method: Fiber::Scheduler#io_pwrite
614 * call-seq: io_pwrite(io, buffer, from, length, offset) -> written length or -errno
615 *
616 * Invoked by IO#pwrite or IO::Buffer#pwrite to write +length+ bytes to +io+
617 * at offset +from+ into a specified +buffer+ (see IO::Buffer) at the given
618 * +offset+.
619 *
620 * This method is semantically the same as #io_write, but it allows to specify
621 * the offset to write to and is often better for asynchronous IO on the same
622 * file.
623 *
624 * The method should be considered _experimental_.
625 *
626 */
627 VALUE
628rb_fiber_scheduler_io_pwrite(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t length, size_t offset)
629{
630 VALUE arguments[] = {
631 io, buffer, OFFT2NUM(from), SIZET2NUM(length), SIZET2NUM(offset)
632 };
633
634 return rb_check_funcall(scheduler, id_io_pwrite, 5, arguments);
635}
636
637 VALUE
638rb_fiber_scheduler_io_read_memory(VALUE scheduler, VALUE io, void *base, size_t size, size_t length)
639{
640 VALUE buffer = rb_io_buffer_new(base, size, RB_IO_BUFFER_LOCKED);
641
642 VALUE result = rb_fiber_scheduler_io_read(scheduler, io, buffer, length, 0);
643
644 rb_io_buffer_free_locked(buffer);
645
646 return result;
647}
648
649 VALUE
650rb_fiber_scheduler_io_write_memory(VALUE scheduler, VALUE io, const void *base, size_t size, size_t length)
651{
652 VALUE buffer = rb_io_buffer_new((void*)base, size, RB_IO_BUFFER_LOCKED|RB_IO_BUFFER_READONLY);
653
654 VALUE result = rb_fiber_scheduler_io_write(scheduler, io, buffer, length, 0);
655
656 rb_io_buffer_free_locked(buffer);
657
658 return result;
659}
660
661 VALUE
662rb_fiber_scheduler_io_pread_memory(VALUE scheduler, VALUE io, rb_off_t from, void *base, size_t size, size_t length)
663{
664 VALUE buffer = rb_io_buffer_new(base, size, RB_IO_BUFFER_LOCKED);
665
666 VALUE result = rb_fiber_scheduler_io_pread(scheduler, io, from, buffer, length, 0);
667
668 rb_io_buffer_free_locked(buffer);
669
670 return result;
671}
672
673 VALUE
674rb_fiber_scheduler_io_pwrite_memory(VALUE scheduler, VALUE io, rb_off_t from, const void *base, size_t size, size_t length)
675{
676 VALUE buffer = rb_io_buffer_new((void*)base, size, RB_IO_BUFFER_LOCKED|RB_IO_BUFFER_READONLY);
677
678 VALUE result = rb_fiber_scheduler_io_pwrite(scheduler, io, from, buffer, length, 0);
679
680 rb_io_buffer_free_locked(buffer);
681
682 return result;
683}
684
685 VALUE
686rb_fiber_scheduler_io_close(VALUE scheduler, VALUE io)
687{
688 VALUE arguments[] = {io};
689
690 return rb_check_funcall(scheduler, id_io_close, 1, arguments);
691}
692
693/*
694 * Document-method: Fiber::Scheduler#address_resolve
695 * call-seq: address_resolve(hostname) -> array_of_strings or nil
696 *
697 * Invoked by any method that performs a non-reverse DNS lookup. The most
698 * notable method is Addrinfo.getaddrinfo, but there are many other.
699 *
700 * The method is expected to return an array of strings corresponding to ip
701 * addresses the +hostname+ is resolved to, or +nil+ if it can not be resolved.
702 *
703 * Fairly exhaustive list of all possible call-sites:
704 *
705 * - Addrinfo.getaddrinfo
706 * - Addrinfo.tcp
707 * - Addrinfo.udp
708 * - Addrinfo.ip
709 * - Addrinfo.new
710 * - Addrinfo.marshal_load
711 * - SOCKSSocket.new
712 * - TCPServer.new
713 * - TCPSocket.new
714 * - IPSocket.getaddress
715 * - TCPSocket.gethostbyname
716 * - UDPSocket#connect
717 * - UDPSocket#bind
718 * - UDPSocket#send
719 * - Socket.getaddrinfo
720 * - Socket.gethostbyname
721 * - Socket.pack_sockaddr_in
722 * - Socket.sockaddr_in
723 * - Socket.unpack_sockaddr_in
724 */
725 VALUE
726rb_fiber_scheduler_address_resolve(VALUE scheduler, VALUE hostname)
727{
728 VALUE arguments[] = {
729 hostname
730 };
731
732 return rb_check_funcall(scheduler, id_address_resolve, 1, arguments);
733}
734
735 struct rb_blocking_operation_wait_arguments {
736 void *(*function)(void *);
737 void *data;
738 rb_unblock_function_t *unblock_function;
739 void *data2;
740 int flags;
741
742 struct rb_fiber_scheduler_blocking_operation_state *state;
743};
744
745static VALUE
746rb_fiber_scheduler_blocking_operation_wait_proc(RB_BLOCK_CALL_FUNC_ARGLIST(value, _arguments))
747{
748 struct rb_blocking_operation_wait_arguments *arguments = (struct rb_blocking_operation_wait_arguments*)_arguments;
749
750 if (arguments->state == NULL) {
751 rb_raise(rb_eRuntimeError, "Blocking function was already invoked!");
752 }
753
754 arguments->state->result = rb_nogvl(arguments->function, arguments->data, arguments->unblock_function, arguments->data2, arguments->flags);
755 arguments->state->saved_errno = rb_errno();
756
757 // Make sure it's only invoked once.
758 arguments->state = NULL;
759
760 return Qnil;
761}
762
763/*
764 * Document-method: Fiber::Scheduler#blocking_operation_wait
765 * call-seq: blocking_operation_wait(work)
766 *
767 * Invoked by Ruby's core methods to run a blocking operation in a non-blocking way.
768 *
769 * Minimal suggested implementation is:
770 *
771 * def blocking_operation_wait(work)
772 * Thread.new(&work).join
773 * end
774 */
775 VALUE rb_fiber_scheduler_blocking_operation_wait(VALUE scheduler, void* (*function)(void *), void *data, rb_unblock_function_t *unblock_function, void *data2, int flags, struct rb_fiber_scheduler_blocking_operation_state *state)
776{
777 struct rb_blocking_operation_wait_arguments arguments = {
778 .function = function,
779 .data = data,
780 .unblock_function = unblock_function,
781 .data2 = data2,
782 .flags = flags,
783 .state = state
784 };
785
786 VALUE proc = rb_proc_new(rb_fiber_scheduler_blocking_operation_wait_proc, (VALUE)&arguments);
787
788 return rb_check_funcall(scheduler, id_blocking_operation_wait, 1, &proc);
789}
790
791/*
792 * Document-method: Fiber::Scheduler#fiber
793 * call-seq: fiber(&block)
794 *
795 * Implementation of the Fiber.schedule. The method is <em>expected</em> to immediately
796 * run the given block of code in a separate non-blocking fiber, and to return that Fiber.
797 *
798 * Minimal suggested implementation is:
799 *
800 * def fiber(&block)
801 * fiber = Fiber.new(blocking: false, &block)
802 * fiber.resume
803 * fiber
804 * end
805 */
806 VALUE
807rb_fiber_scheduler_fiber(VALUE scheduler, int argc, VALUE *argv, int kw_splat)
808{
809 return rb_funcall_passing_block_kw(scheduler, id_fiber_schedule, argc, argv, kw_splat);
810}
RUBY_ASSERT
#define RUBY_ASSERT(...)
Asserts that the given expression is truthy if and only if RUBY_DEBUG is truthy.
Definition assert.h:219
buffer.h
rb_define_method
#define rb_define_method(klass, mid, func, arity)
Defines klass#mid.
Definition cxxanyargs.hpp:670
rb_define_class_under
VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
Defines a class under the namespace of outer.
Definition class.c:1012
SIZET2NUM
#define SIZET2NUM
Old name of RB_SIZE2NUM.
Definition size_t.h:62
Qnil
#define Qnil
Old name of RUBY_Qnil.
Definition special_consts.h:60
rb_eRuntimeError
VALUE rb_eRuntimeError
RuntimeError exception.
Definition error.c:1428
rb_ensure
VALUE rb_ensure(VALUE(*b_proc)(VALUE), VALUE data1, VALUE(*e_proc)(VALUE), VALUE data2)
An equivalent to ensure clause.
Definition eval.c:1066
rb_funcall
VALUE rb_funcall(VALUE recv, ID mid, int n,...)
Calls a method.
Definition vm_eval.c:1099
rb_funcall_passing_block_kw
VALUE rb_funcall_passing_block_kw(VALUE recv, ID mid, int argc, const VALUE *argv, int kw_splat)
Identical to rb_funcallv_passing_block(), except you can specify how to handle the last element of th...
Definition vm_eval.c:1169
rb_unblock_function_t
void rb_unblock_function_t(void *)
This is the type of UBFs.
Definition thread.h:336
rb_respond_to
int rb_respond_to(VALUE obj, ID mid)
Queries if the object responds to the method.
Definition vm_method.c:2973
rb_check_funcall
VALUE rb_check_funcall(VALUE recv, ID mid, int argc, const VALUE *argv)
Identical to rb_funcallv(), except it returns RUBY_Qundef instead of raising rb_eNoMethodError.
Definition vm_eval.c:668
rb_intern_const
static ID rb_intern_const(const char *str)
This is a "tiny optimisation" over rb_intern().
Definition symbol.h:284
io.h
rb_io_timeout
VALUE rb_io_timeout(VALUE io)
Get the timeout associated with the specified io object.
Definition io.c:857
RUBY_IO_READABLE
@ RUBY_IO_READABLE
IO::READABLE
Definition io.h:82
RUBY_IO_WRITABLE
@ RUBY_IO_WRITABLE
IO::WRITABLE
Definition io.h:83
thread.h
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_UINT2NUM
#define RB_UINT2NUM
Just another name of rb_uint2num_inline.
Definition int.h:39
RB_INT2NUM
#define RB_INT2NUM
Just another name of rb_int2num_inline.
Definition int.h:37
RB_BLOCK_CALL_FUNC_ARGLIST
#define RB_BLOCK_CALL_FUNC_ARGLIST(yielded_arg, callback_arg)
Shim for block function parameters.
Definition iterator.h:58
ruby::backward::cxxanyargs::rb_proc_new
VALUE rb_proc_new(type *q, VALUE w)
Creates a rb_cProc instance.
Definition cxxanyargs.hpp:394
OFFT2NUM
#define OFFT2NUM
Converts a C's off_t into an instance of rb_cInteger.
Definition off_t.h:33
PIDT2NUM
#define PIDT2NUM
Converts a C's pid_t into an instance of rb_cInteger.
Definition pid_t.h:28
errno
#define errno
Ractor-aware version of errno.
Definition ruby.h:388
scheduler.h
Scheduler APIs.
rb_fiber_scheduler_blocking_operation_wait
VALUE rb_fiber_scheduler_blocking_operation_wait(VALUE scheduler, void *(*function)(void *), void *data, rb_unblock_function_t *unblock_function, void *data2, int flags, struct rb_fiber_scheduler_blocking_operation_state *state)
Defer the execution of the passed function to the scheduler.
Definition scheduler.c:775
rb_fiber_scheduler_current
VALUE rb_fiber_scheduler_current(void)
Identical to rb_fiber_scheduler_get(), except it also returns RUBY_Qnil in case of a blocking fiber.
Definition scheduler.c:229
rb_fiber_scheduler_io_pread_memory
VALUE rb_fiber_scheduler_io_pread_memory(VALUE scheduler, VALUE io, rb_off_t from, void *base, size_t size, size_t length)
Non-blocking pread from the passed IO using a native buffer.
Definition scheduler.c:662
rb_fiber_scheduler_make_timeout
VALUE rb_fiber_scheduler_make_timeout(struct timeval *timeout)
Converts the passed timeout to an expression that rb_fiber_scheduler_block() etc.
Definition scheduler.c:272
rb_fiber_scheduler_io_wait_readable
VALUE rb_fiber_scheduler_io_wait_readable(VALUE scheduler, VALUE io)
Non-blocking wait until the passed IO is ready for reading.
Definition scheduler.c:474
rb_fiber_scheduler_io_read_memory
VALUE rb_fiber_scheduler_io_read_memory(VALUE scheduler, VALUE io, void *base, size_t size, size_t length)
Non-blocking read from the passed IO using a native buffer.
Definition scheduler.c:638
rb_fiber_scheduler_io_pwrite
VALUE rb_fiber_scheduler_io_pwrite(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t length, size_t offset)
Non-blocking write to the passed IO at the specified offset.
Definition scheduler.c:628
rb_fiber_scheduler_kernel_sleepv
VALUE rb_fiber_scheduler_kernel_sleepv(VALUE scheduler, int argc, VALUE *argv)
Identical to rb_fiber_scheduler_kernel_sleep(), except it can pass multiple arguments.
Definition scheduler.c:299
rb_fiber_scheduler_io_wait
VALUE rb_fiber_scheduler_io_wait(VALUE scheduler, VALUE io, VALUE events, VALUE timeout)
Non-blocking version of rb_io_wait().
Definition scheduler.c:468
rb_fiber_scheduler_io_select
VALUE rb_fiber_scheduler_io_select(VALUE scheduler, VALUE readables, VALUE writables, VALUE exceptables, VALUE timeout)
Non-blocking version of IO.select.
Definition scheduler.c:495
rb_fiber_scheduler_io_read
VALUE rb_fiber_scheduler_io_read(VALUE scheduler, VALUE io, VALUE buffer, size_t length, size_t offset)
Non-blocking read from the passed IO.
Definition scheduler.c:541
rb_fiber_scheduler_io_selectv
VALUE rb_fiber_scheduler_io_selectv(VALUE scheduler, int argc, VALUE *argv)
Non-blocking version of IO.select, argv variant.
Definition scheduler.c:504
rb_fiber_scheduler_process_wait
VALUE rb_fiber_scheduler_process_wait(VALUE scheduler, rb_pid_t pid, int flags)
Non-blocking waitpid.
Definition scheduler.c:369
rb_fiber_scheduler_block
VALUE rb_fiber_scheduler_block(VALUE scheduler, VALUE blocker, VALUE timeout)
Non-blocking wait for the passed "blocker", which is for instance Thread.join or Mutex....
Definition scheduler.c:393
rb_fiber_scheduler_io_pread
VALUE rb_fiber_scheduler_io_pread(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t length, size_t offset)
Non-blocking read from the passed IO at the specified offset.
Definition scheduler.c:565
rb_fiber_scheduler_io_pwrite_memory
VALUE rb_fiber_scheduler_io_pwrite_memory(VALUE scheduler, VALUE io, rb_off_t from, const void *base, size_t size, size_t length)
Non-blocking pwrite to the passed IO using a native buffer.
Definition scheduler.c:674
rb_fiber_scheduler_io_write
VALUE rb_fiber_scheduler_io_write(VALUE scheduler, VALUE io, VALUE buffer, size_t length, size_t offset)
Non-blocking write to the passed IO.
Definition scheduler.c:603
rb_fiber_scheduler_close
VALUE rb_fiber_scheduler_close(VALUE scheduler)
Closes the passed scheduler object.
Definition scheduler.c:250
rb_fiber_scheduler_current_for_thread
VALUE rb_fiber_scheduler_current_for_thread(VALUE thread)
Identical to rb_fiber_scheduler_current(), except it queries for that of the passed thread instead of...
Definition scheduler.c:234
rb_fiber_scheduler_kernel_sleep
VALUE rb_fiber_scheduler_kernel_sleep(VALUE scheduler, VALUE duration)
Non-blocking sleep.
Definition scheduler.c:293
rb_fiber_scheduler_address_resolve
VALUE rb_fiber_scheduler_address_resolve(VALUE scheduler, VALUE hostname)
Non-blocking DNS lookup.
Definition scheduler.c:726
rb_fiber_scheduler_set
VALUE rb_fiber_scheduler_set(VALUE scheduler)
Destructively assigns the passed scheduler to that of the current thread that is calling this functio...
Definition scheduler.c:190
rb_fiber_scheduler_io_write_memory
VALUE rb_fiber_scheduler_io_write_memory(VALUE scheduler, VALUE io, const void *base, size_t size, size_t length)
Non-blocking write to the passed IO using a native buffer.
Definition scheduler.c:650
rb_fiber_scheduler_io_wait_writable
VALUE rb_fiber_scheduler_io_wait_writable(VALUE scheduler, VALUE io)
Non-blocking wait until the passed IO is ready for writing.
Definition scheduler.c:480
rb_fiber_scheduler_io_close
VALUE rb_fiber_scheduler_io_close(VALUE scheduler, VALUE io)
Non-blocking close the given IO.
Definition scheduler.c:686
rb_fiber_scheduler_get
VALUE rb_fiber_scheduler_get(void)
Queries the current scheduler of the current thread that is calling this function.
Definition scheduler.c:144
rb_fiber_scheduler_unblock
VALUE rb_fiber_scheduler_unblock(VALUE scheduler, VALUE blocker, VALUE fiber)
Wakes up a fiber previously blocked using rb_fiber_scheduler_block().
Definition scheduler.c:412
rb_fiber_scheduler_fiber
VALUE rb_fiber_scheduler_fiber(VALUE scheduler, int argc, VALUE *argv, int kw_splat)
Create and schedule a non-blocking fiber.
Definition scheduler.c:807
rb_blocking_operation_wait_arguments
Definition scheduler.c:735
rb_execution_context_struct
Definition vm_core.h:1022
rb_fiber_scheduler_blocking_operation_state
Definition scheduler.h:394
rb_thread_struct
Definition vm_core.h:1108
timeval
Definition missing.h:63
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