Ruby: include/ruby/fiber/scheduler.h Source File

Ruby 4.0.5p0 (2026-05-20 revision 64336ffd0ee9e1f4c05891695a3d7b49cb709721)

scheduler.h
Go to the documentation of this file.
1#ifndef RUBY_FIBER_SCHEDULER_H /*-*-C++-*-vi:se ft=cpp:*/
2#define RUBY_FIBER_SCHEDULER_H
12#include "ruby/internal/config.h"
13
14#include <errno.h>
15
16#ifdef STDC_HEADERS
17#include <stddef.h> /* size_t */
18#endif
19
20#include "ruby/ruby.h"
21#include "ruby/internal/dllexport.h"
22#include "ruby/internal/arithmetic.h"
23
24 RBIMPL_SYMBOL_EXPORT_BEGIN()
25
26// Version 3: Adds support for `fiber_interrupt`.
27#define RUBY_FIBER_SCHEDULER_VERSION 3
28
29struct timeval;
30struct rb_thread_struct;
31
49static inline VALUE
50rb_fiber_scheduler_io_result(ssize_t result, int error)
51{
52 if (result == -1) {
53 return RB_INT2NUM(-error);
54 }
55 else {
56 return RB_SIZE2NUM(result);
57 }
58}
59
71static inline ssize_t
72rb_fiber_scheduler_io_result_apply(VALUE result)
73{
74 if (RB_FIXNUM_P(result) && RB_NUM2INT(result) < 0) {
75 errno = -RB_NUM2INT(result);
76 return -1;
77 }
78 else {
79 return RB_NUM2SIZE(result);
80 }
81}
82
92 VALUE rb_fiber_scheduler_get(void);
93
108 VALUE rb_fiber_scheduler_set(VALUE scheduler);
109
118 VALUE rb_fiber_scheduler_current(void);
119
129 VALUE rb_fiber_scheduler_current_for_thread(VALUE thread);
130
140 VALUE rb_fiber_scheduler_current_for_threadptr(struct rb_thread_struct *thread);
141
150 VALUE rb_fiber_scheduler_make_timeout(struct timeval *timeout);
151
159 VALUE rb_fiber_scheduler_close(VALUE scheduler);
160
169 VALUE rb_fiber_scheduler_kernel_sleep(VALUE scheduler, VALUE duration);
170
180 VALUE rb_fiber_scheduler_kernel_sleepv(VALUE scheduler, int argc, VALUE * argv);
181
188 VALUE rb_fiber_scheduler_yield(VALUE scheduler);
189
190/* Description TBW */
191#if 0
192 VALUE rb_fiber_scheduler_timeout_after(VALUE scheduler, VALUE timeout, VALUE exception, VALUE message);
193 VALUE rb_fiber_scheduler_timeout_afterv(VALUE scheduler, int argc, VALUE * argv);
194int rb_fiber_scheduler_supports_process_wait(VALUE scheduler);
195#endif
196
206 VALUE rb_fiber_scheduler_process_wait(VALUE scheduler, rb_pid_t pid, int flags);
207
218 VALUE rb_fiber_scheduler_block(VALUE scheduler, VALUE blocker, VALUE timeout);
219
230 VALUE rb_fiber_scheduler_unblock(VALUE scheduler, VALUE blocker, VALUE fiber);
231
245 VALUE rb_fiber_scheduler_io_wait(VALUE scheduler, VALUE io, VALUE events, VALUE timeout);
246
256 VALUE rb_fiber_scheduler_io_wait_readable(VALUE scheduler, VALUE io);
257
267 VALUE rb_fiber_scheduler_io_wait_writable(VALUE scheduler, VALUE io);
268
282 VALUE rb_fiber_scheduler_io_select(VALUE scheduler, VALUE readables, VALUE writables, VALUE exceptables, VALUE timeout);
283
287 VALUE rb_fiber_scheduler_io_selectv(VALUE scheduler, int argc, VALUE *argv);
288
300 VALUE rb_fiber_scheduler_io_read(VALUE scheduler, VALUE io, VALUE buffer, size_t length, size_t offset);
301
313 VALUE rb_fiber_scheduler_io_write(VALUE scheduler, VALUE io, VALUE buffer, size_t length, size_t offset);
314
327 VALUE rb_fiber_scheduler_io_pread(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t length, size_t offset);
328
341 VALUE rb_fiber_scheduler_io_pwrite(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t length, size_t offset);
342
354 VALUE rb_fiber_scheduler_io_read_memory(VALUE scheduler, VALUE io, void *base, size_t size, size_t length);
355
367 VALUE rb_fiber_scheduler_io_write_memory(VALUE scheduler, VALUE io, const void *base, size_t size, size_t length);
368
381 VALUE rb_fiber_scheduler_io_pread_memory(VALUE scheduler, VALUE io, rb_off_t from, void *base, size_t size, size_t length);
382
395 VALUE rb_fiber_scheduler_io_pwrite_memory(VALUE scheduler, VALUE io, rb_off_t from, const void *base, size_t size, size_t length);
396
405 VALUE rb_fiber_scheduler_io_close(VALUE scheduler, VALUE io);
406
415 VALUE rb_fiber_scheduler_address_resolve(VALUE scheduler, VALUE hostname);
416
417// The state of the blocking operation execution.
418 struct rb_fiber_scheduler_blocking_operation_state {
419 void *result;
420 int saved_errno;
421};
422
423// The opaque handle for the blocking operation.
424typedef struct rb_fiber_scheduler_blocking_operation rb_fiber_scheduler_blocking_operation_t;
425
437rb_fiber_scheduler_blocking_operation_t *rb_fiber_scheduler_blocking_operation_extract(VALUE self);
438
450int rb_fiber_scheduler_blocking_operation_execute(rb_fiber_scheduler_blocking_operation_t *blocking_operation);
451
463int rb_fiber_scheduler_blocking_operation_cancel(rb_fiber_scheduler_blocking_operation_t *blocking_operation);
464
478 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);
479
490 VALUE rb_fiber_scheduler_fiber_interrupt(VALUE scheduler, VALUE fiber, VALUE exception);
491
501 VALUE rb_fiber_scheduler_fiber(VALUE scheduler, int argc, VALUE *argv, int kw_splat);
502
503 RBIMPL_SYMBOL_EXPORT_END()
504
505#endif /* RUBY_FIBER_SCHEDULER_H */
arithmetic.h
Conversion between C's arithmetic types and Ruby's numeric types.
dllexport.h
Tweaking visibility of C variables/functions.
RBIMPL_SYMBOL_EXPORT_END
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition dllexport.h:74
RBIMPL_SYMBOL_EXPORT_BEGIN
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:65
rb_unblock_function_t
void rb_unblock_function_t(void *)
This is the type of UBFs.
Definition thread.h:336
RB_NUM2INT
#define RB_NUM2INT
Just another name of rb_num2int_inline.
Definition int.h:38
RB_INT2NUM
#define RB_INT2NUM
Just another name of rb_int2num_inline.
Definition int.h:37
ruby.h
errno
#define errno
Ractor-aware version of errno.
Definition ruby.h:388
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:1104
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:471
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:1006
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:522
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:756
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:982
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:962
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:549
rb_fiber_scheduler_fiber_interrupt
VALUE rb_fiber_scheduler_fiber_interrupt(VALUE scheduler, VALUE fiber, VALUE exception)
Interrupt a fiber by raising an exception.
Definition scheduler.c:1144
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:742
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:777
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:830
rb_fiber_scheduler_blocking_operation_cancel
int rb_fiber_scheduler_blocking_operation_cancel(rb_fiber_scheduler_blocking_operation_t *blocking_operation)
Cancel a blocking operation.
Definition scheduler.c:1206
rb_fiber_scheduler_io_result_apply
static ssize_t rb_fiber_scheduler_io_result_apply(VALUE result)
Apply an io result to the local thread, returning the value of the original system call that created ...
Definition scheduler.h:72
rb_fiber_scheduler_io_result
static VALUE rb_fiber_scheduler_io_result(ssize_t result, int error)
Wrap a ssize_t and int errno into a single VALUE.
Definition scheduler.h:50
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:786
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:636
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:660
rb_fiber_scheduler_blocking_operation_execute
int rb_fiber_scheduler_blocking_operation_execute(rb_fiber_scheduler_blocking_operation_t *blocking_operation)
Execute blocking operation from handle (GVL not required).
Definition scheduler.c:206
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:869
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:1018
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:922
rb_fiber_scheduler_close
VALUE rb_fiber_scheduler_close(VALUE scheduler)
Closes the passed scheduler object.
Definition scheduler.c:500
rb_fiber_scheduler_blocking_operation_extract
rb_fiber_scheduler_blocking_operation_t * rb_fiber_scheduler_blocking_operation_extract(VALUE self)
Extract the blocking operation handle from a BlockingOperationRuby object.
Definition scheduler.c:191
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 value inst...
Definition scheduler.c:479
rb_fiber_scheduler_kernel_sleep
VALUE rb_fiber_scheduler_kernel_sleep(VALUE scheduler, VALUE duration)
Non-blocking sleep.
Definition scheduler.c:543
rb_fiber_scheduler_address_resolve
VALUE rb_fiber_scheduler_address_resolve(VALUE scheduler, VALUE hostname)
Non-blocking DNS lookup.
Definition scheduler.c:1078
rb_fiber_scheduler_yield
VALUE rb_fiber_scheduler_yield(VALUE scheduler)
Yield to the scheduler, to be resumed on the next scheduling cycle.
Definition scheduler.c:561
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:433
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:994
rb_fiber_scheduler_current_for_threadptr
VALUE rb_fiber_scheduler_current_for_threadptr(struct rb_thread_struct *thread)
Identical to rb_fiber_scheduler_current_for_thread(), except it expects a threadptr instead of a thre...
Definition scheduler.c:484
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:762
rb_fiber_scheduler_io_close
VALUE rb_fiber_scheduler_io_close(VALUE scheduler, VALUE io)
Non-blocking close the given IO.
Definition scheduler.c:1038
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:383
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:679
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:1191
RB_SIZE2NUM
#define RB_SIZE2NUM
Converts a C's size_t into an instance of rb_cInteger.
Definition size_t.h:31
RB_NUM2SIZE
#define RB_NUM2SIZE
Converts an instance of rb_cInteger into C's size_t.
Definition size_t.h:47
RB_FIXNUM_P
static bool RB_FIXNUM_P(VALUE obj)
Checks if the given object is a so-called Fixnum.
Definition special_consts.h:247
rb_fiber_scheduler_blocking_operation_state
Definition scheduler.h:418
rb_fiber_scheduler_blocking_operation
Definition scheduler.c:66
rb_thread_struct
Definition vm_core.h:1130
timeval
Definition missing.h:63
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40