Ruby 3.4.5p51 (2025-07-16 revision 20cda200d3ce092571d0b5d342dadca69636cb0f)
|
Scheduler APIs. More...
#include "ruby/internal/config.h"
#include <errno.h>
#include "ruby/ruby.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/arithmetic.h"
Go to the source code of this file.
Data Structures | |
struct | rb_fiber_scheduler_blocking_operation_state |
Macros | |
#define | RUBY_FIBER_SCHEDULER_VERSION 2 |
Functions | |
static VALUE | rb_fiber_scheduler_io_result (ssize_t result, int error) |
Wrap a ssize_t and int errno into a single VALUE. | |
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 it and updating int errno. | |
VALUE | rb_fiber_scheduler_get (void) |
Queries the current scheduler of the current thread that is calling this function. | |
VALUE | rb_fiber_scheduler_set (VALUE scheduler) |
Destructively assigns the passed scheduler to that of the current thread that is calling this function. | |
VALUE | rb_fiber_scheduler_current (void) |
Identical to rb_fiber_scheduler_get(), except it also returns RUBY_Qnil in case of a blocking fiber. | |
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 the implicit current one. | |
VALUE | rb_fiber_scheduler_make_timeout (struct timeval *timeout) |
Converts the passed timeout to an expression that rb_fiber_scheduler_block() etc. | |
VALUE | rb_fiber_scheduler_close (VALUE scheduler) |
Closes the passed scheduler object. | |
VALUE | rb_fiber_scheduler_kernel_sleep (VALUE scheduler, VALUE duration) |
Non-blocking sleep. | |
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. | |
VALUE | rb_fiber_scheduler_process_wait (VALUE scheduler, rb_pid_t pid, int flags) |
Non-blocking waitpid. | |
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.lock. | |
VALUE | rb_fiber_scheduler_unblock (VALUE scheduler, VALUE blocker, VALUE fiber) |
Wakes up a fiber previously blocked using rb_fiber_scheduler_block(). | |
VALUE | rb_fiber_scheduler_io_wait (VALUE scheduler, VALUE io, VALUE events, VALUE timeout) |
Non-blocking version of rb_io_wait(). | |
VALUE | rb_fiber_scheduler_io_wait_readable (VALUE scheduler, VALUE io) |
Non-blocking wait until the passed IO is ready for reading. | |
VALUE | rb_fiber_scheduler_io_wait_writable (VALUE scheduler, VALUE io) |
Non-blocking wait until the passed IO is ready for writing. | |
VALUE | rb_fiber_scheduler_io_select (VALUE scheduler, VALUE readables, VALUE writables, VALUE exceptables, VALUE timeout) |
Non-blocking version of IO.select. | |
VALUE | rb_fiber_scheduler_io_selectv (VALUE scheduler, int argc, VALUE *argv) |
Non-blocking version of IO.select, argv variant. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
VALUE | rb_fiber_scheduler_io_close (VALUE scheduler, VALUE io) |
Non-blocking close the given IO. | |
VALUE | rb_fiber_scheduler_address_resolve (VALUE scheduler, VALUE hostname) |
Non-blocking DNS lookup. | |
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. | |
VALUE | rb_fiber_scheduler_fiber (VALUE scheduler, int argc, VALUE *argv, int kw_splat) |
Create and schedule a non-blocking fiber. |
Scheduler APIs.
Definition in file scheduler.h.
#define RUBY_FIBER_SCHEDULER_VERSION 2 |
Definition at line 26 of file scheduler.h.
Non-blocking DNS lookup.
[in] | scheduler | Target scheduler. |
[in] | hostname | A host name to query. |
RUBY_Qundef | scheduler doesn't have #address_resolve. |
Definition at line 704 of file scheduler.c.
Referenced by rb_fiber_scheduler_address_resolve().
Non-blocking wait for the passed "blocker", which is for instance Thread.join or Mutex.lock.
Depending on scheduler implementation, this for instance switches to another fiber etc.
[in] | scheduler | Target scheduler. |
[in] | blocker | What blocks the current fiber. |
[in] | timeout | Numeric timeout. |
Definition at line 392 of file scheduler.c.
Referenced by rb_fiber_scheduler_block().
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.
[in] | scheduler | Target scheduler. |
[in] | function | The function to run. |
[in] | data | The data to pass to the function. |
[in] | unblock_function | The unblock function to use to interrupt the operation. |
[in] | data2 | The data to pass to the unblock function. |
[in] | flags | Flags passed to rb_nogvl. |
[out] | state | The result and errno of the operation. |
RUBY_Qundef | scheduler doesn't have #blocking_operation_wait. |
Definition at line 753 of file scheduler.c.
Referenced by rb_fiber_scheduler_blocking_operation_wait(), and rb_nogvl().
Closes the passed scheduler object.
This expects the scheduler to wait for all fibers. Thus the scheduler's main loop tends to start here.
[in] | scheduler | Target scheduler. |
Definition at line 249 of file scheduler.c.
Referenced by rb_fiber_scheduler_close().
VALUE rb_fiber_scheduler_current | ( | void | ) |
Identical to rb_fiber_scheduler_get(), except it also returns RUBY_Qnil in case of a blocking fiber.
As blocking fibers do not participate schedulers' scheduling this function can be handy.
RUBY_Qnil | No scheduler is in effect. |
otherwise | The scheduler that is in effect, if any. |
Definition at line 228 of file scheduler.c.
Referenced by rb_io_wait(), rb_io_wait_readable(), rb_io_wait_writable(), rb_nogvl(), and rb_process_status_wait().
Identical to rb_fiber_scheduler_current(), except it queries for that of the passed thread instead of the implicit current one.
[in] | thread | Target thread. |
rb_eTypeError | `thread` is not a thread. |
RUBY_Qnil | No scheduler is in effect in thread. |
otherwise | The scheduler that is in effect in thread. |
Definition at line 233 of file scheduler.c.
Referenced by rb_fiber_scheduler_current_for_thread().
Create and schedule a non-blocking fiber.
Definition at line 785 of file scheduler.c.
Referenced by rb_fiber_scheduler_fiber().
VALUE rb_fiber_scheduler_get | ( | void | ) |
Queries the current scheduler of the current thread that is calling this function.
RUBY_Qnil | No scheduler has been set so far to this thread (which is the default). |
otherwise | The scheduler that was last set for the current thread with rb_fiber_scheduler_set(). |
Definition at line 143 of file scheduler.c.
Non-blocking close the given IO.
[in] | scheduler | Target scheduler. |
[in] | io | An io object to close. |
RUBY_Qundef | scheduler doesn't have #io_close. |
Definition at line 664 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_close().
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.
[in] | scheduler | Target scheduler. |
[in] | io | An io object to read from. |
[in] | from | The offset to read from. |
[in] | buffer | The buffer to read to. |
[in] | length | The minimum number of bytes to read. |
[in] | offset | The offset in the buffer to read to. |
RUBY_Qundef | scheduler doesn't have #io_read. |
Definition at line 543 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_pread(), and 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.
[in] | scheduler | Target scheduler. |
[in] | io | An io object to read from. |
[in] | from | The offset to read from. |
[in] | base | The memory to read to. |
[in] | size | Size of the memory. |
[in] | length | The minimum number of bytes to read. |
RUBY_Qundef | scheduler doesn't have #io_read. |
Definition at line 640 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_pread_memory().
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.
[in] | scheduler | Target scheduler. |
[in] | io | An io object to write to. |
[in] | from | The offset to write to. |
[in] | buffer | The buffer to write from. |
[in] | length | The minimum number of bytes to write. |
[in] | offset | The offset in the buffer to write from. |
RUBY_Qundef | scheduler doesn't have #io_write. |
Definition at line 606 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_pwrite(), and 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.
[in] | scheduler | Target scheduler. |
[in] | io | An io object to write to. |
[in] | from | The offset to write from. |
[in] | base | The memory to write from. |
[in] | size | Size of the memory. |
[in] | length | The minimum number of bytes to write. |
RUBY_Qundef | scheduler doesn't have #io_write. |
Definition at line 652 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_pwrite_memory().
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.
[in] | scheduler | Target scheduler. |
[in] | io | An io object to read from. |
[in] | buffer | The buffer to read to. |
[in] | length | The minimum number of bytes to read. |
[in] | offset | The offset in the buffer to read from. |
RUBY_Qundef | scheduler doesn't have #io_read. |
Definition at line 519 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_read(), and 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.
[in] | scheduler | Target scheduler. |
[in] | io | An io object to read from. |
[in] | base | The memory to read to. |
[in] | size | Size of the memory. |
[in] | length | The minimum number of bytes to read. |
RUBY_Qundef | scheduler doesn't have #io_read. |
Definition at line 616 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_read_memory().
|
inlinestatic |
Wrap a ssize_t and int errno into a single VALUE.
This interface should be used to safely capture results from system calls like read and write.
You should use rb_fiber_scheduler_io_result_apply to unpack the result of this value and update int errno.
You should not directly try to interpret the result value as it is considered an opaque representation. However, the general representation is an integer in the range of [-int errno, size_t size]. Linux generally restricts the result of system calls like read and write to <= 2^31 which means this will typically fit within a single FIXNUM.
[in] | result | The result of the system call. |
[in] | error | The value of errno. |
Definition at line 48 of file scheduler.h.
|
inlinestatic |
Apply an io result to the local thread, returning the value of the original system call that created it and updating int errno.
You should not directly try to interpret the result value as it is considered an opaque representation.
[in] | result | The VALUE which contains an errno and/or result size. |
Definition at line 70 of file scheduler.h.
VALUE rb_fiber_scheduler_io_select | ( | VALUE | scheduler, |
VALUE | readables, | ||
VALUE | writables, | ||
VALUE | exceptables, | ||
VALUE | timeout ) |
Non-blocking version of IO.select.
It's possible that this will be emulated using a thread, so you should not rely on it for high performance.
[in] | scheduler | Target scheduler. |
[in] | readables | An array of readable objects. |
[in] | writables | An array of writable objects. |
[in] | exceptables | An array of objects that might encounter exceptional conditions. |
[in] | timeout | Numeric timeout or nil. |
Definition at line 473 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_select().
Non-blocking version of IO.select, argv variant.
Definition at line 482 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_select(), and rb_fiber_scheduler_io_selectv().
Non-blocking version of rb_io_wait().
Depending on scheduler implementation, this for instance switches to another fiber etc.
The "events" here is a Ruby level integer, which is an OR-ed value of IO::READABLE, IO::WRITABLE, and IO::PRIORITY.
[in] | scheduler | Target scheduler. |
[in] | io | An io object to wait. |
[in] | events | An integer set of interests. |
[in] | timeout | Numeric timeout. |
Definition at line 446 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_wait(), rb_fiber_scheduler_io_wait_readable(), rb_fiber_scheduler_io_wait_writable(), and rb_io_wait().
Non-blocking wait until the passed IO is ready for reading.
This is a special case of rb_fiber_scheduler_io_wait(), where the interest is IO::READABLE and timeout is never.
[in] | scheduler | Target scheduler. |
[in] | io | An io object to wait. |
Definition at line 452 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_wait_readable(), and rb_io_wait_readable().
Non-blocking wait until the passed IO is ready for writing.
This is a special case of rb_fiber_scheduler_io_wait(), where the interest is IO::WRITABLE and timeout is never.
[in] | scheduler | Target scheduler. |
[in] | io | An io object to wait. |
Definition at line 458 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_wait_writable(), and rb_io_wait_writable().
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.
[in] | scheduler | Target scheduler. |
[in] | io | An io object to write to. |
[in] | buffer | The buffer to write from. |
[in] | length | The minimum number of bytes to write. |
[in] | offset | The offset in the buffer to write from. |
RUBY_Qundef | scheduler doesn't have #io_write. |
Definition at line 581 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_write(), and 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.
[in] | scheduler | Target scheduler. |
[in] | io | An io object to write to. |
[in] | base | The memory to write from. |
[in] | size | Size of the memory. |
[in] | length | The minimum number of bytes to write. |
RUBY_Qundef | scheduler doesn't have #io_write. |
Definition at line 628 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_write_memory().
Non-blocking sleep.
Depending on scheduler implementation, this for instance switches to another fiber etc.
[in] | scheduler | Target scheduler. |
[in] | duration | Passed as-is to scheduler.kernel_sleep. |
Definition at line 292 of file scheduler.c.
Referenced by rb_fiber_scheduler_kernel_sleep().
Identical to rb_fiber_scheduler_kernel_sleep(), except it can pass multiple arguments.
[in] | scheduler | Target scheduler. |
[in] | argc | Number of objects of argv. |
[in] | argv | Passed as-is to scheduler.kernel_sleep |
Definition at line 298 of file scheduler.c.
Referenced by rb_fiber_scheduler_kernel_sleepv().
Converts the passed timeout to an expression that rb_fiber_scheduler_block() etc.
expects.
[in] | timeout | A duration (can be NULL). |
RUBY_Qnil | No timeout (blocks indefinitely). |
otherwise | A timeout object. |
Definition at line 271 of file scheduler.c.
Referenced by rb_fiber_scheduler_make_timeout().
Non-blocking waitpid.
Depending on scheduler implementation, this for instance switches to another fiber etc.
[in] | scheduler | Target scheduler. |
[in] | pid | Process ID to wait. |
[in] | flags | Wait flags, e.g. WUNTRACED. |
Definition at line 368 of file scheduler.c.
Referenced by rb_fiber_scheduler_process_wait(), and rb_process_status_wait().
Destructively assigns the passed scheduler to that of the current thread that is calling this function.
If the scheduler is set, non-blocking fibers (created by Fiber.new with blocking: false, or by Fiber.schedule) call that scheduler's hook methods on potentially blocking operations, and the current thread will call scheduler's #close method on finalisation (allowing the scheduler to properly manage all non-finished fibers). scheduler can be an object of any class corresponding to Fiber::Scheduler interface. Its implementation is up to the user.
[in] | scheduler | The scheduler to set. |
rb_eArgError | `scheduler` does not conform the interface. |
Definition at line 189 of file scheduler.c.
Referenced by rb_fiber_scheduler_set().
Wakes up a fiber previously blocked using rb_fiber_scheduler_block().
[in] | scheduler | Target scheduler. |
[in] | blocker | What was awaited for. |
[in] | fiber | What to unblock. |
Definition at line 411 of file scheduler.c.
Referenced by rb_fiber_scheduler_unblock().