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