Ruby 3.5.0dev (2025-06-06 revision dde9fca63bf4bf56050c734adca3eaae70506179)
|
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 3 |
Typedefs | |
typedef struct rb_fiber_scheduler_blocking_operation | rb_fiber_scheduler_blocking_operation_t |
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. | |
rb_fiber_scheduler_blocking_operation_t * | rb_fiber_scheduler_blocking_operation_extract (VALUE self) |
Extract the blocking operation handle from a BlockingOperationRuby object. | |
int | rb_fiber_scheduler_blocking_operation_execute (rb_fiber_scheduler_blocking_operation_t *blocking_operation) |
Execute blocking operation from handle (GVL not required). | |
int | rb_fiber_scheduler_blocking_operation_cancel (rb_fiber_scheduler_blocking_operation_t *blocking_operation) |
Cancel a blocking operation. | |
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_interrupt (VALUE scheduler, VALUE fiber, VALUE exception) |
Interrupt a fiber by raising an exception. | |
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 3 |
Definition at line 27 of file scheduler.h.
Definition at line 404 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 . |
scheduler.address_resolve
returns. Definition at line 1016 of file scheduler.c.
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. |
scheduler.block
returns. Definition at line 622 of file scheduler.c.
int rb_fiber_scheduler_blocking_operation_cancel | ( | rb_fiber_scheduler_blocking_operation_t * | blocking_operation | ) |
Cancel a blocking operation.
This function cancels a blocking operation. If the operation is queued, it just marks it as cancelled. If it's executing, it marks it as cancelled and calls the unblock function to interrupt the operation.
blocking_operation | The opaque struct pointer |
Definition at line 1120 of file scheduler.c.
int rb_fiber_scheduler_blocking_operation_execute | ( | rb_fiber_scheduler_blocking_operation_t * | blocking_operation | ) |
Execute blocking operation from handle (GVL not required).
This function executes a blocking operation using the opaque handle obtained from rb_fiber_scheduler_blocking_operation_extract. It can be called from native threads without holding the GVL.
[in] | blocking_operation | The opaque handle. |
Definition at line 201 of file scheduler.c.
rb_fiber_scheduler_blocking_operation_t * rb_fiber_scheduler_blocking_operation_extract | ( | VALUE | self | ) |
Extract the blocking operation handle from a BlockingOperationRuby object.
This function safely extracts the opaque handle from a BlockingOperation VALUE while holding the GVL. The returned pointer can be passed to worker threads and used with rb_fiber_scheduler_blocking_operation_execute.
[in] | self | The BlockingOperation VALUE to extract from |
Definition at line 186 of file scheduler.c.
VALUE rb_fiber_scheduler_blocking_operation_wait | ( | VALUE | scheduler, |
void *(*)(void *) | function, | ||
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 . |
scheduler.blocking_operation_wait
returns. Definition at line 1041 of file scheduler.c.
Referenced by 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. |
scheduler.close
returns. Definition at line 479 of file scheduler.c.
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 458 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 463 of file scheduler.c.
Create and schedule a non-blocking fiber.
[in] | scheduler | Target scheduler. |
[in] | argc | Number of arguments in argv. |
[in] | argv | Array of arguments to pass to the fiber. |
[in] | kw_splat | Whether to expand last argument as keywords. |
Definition at line 1105 of file scheduler.c.
Interrupt a fiber by raising an exception.
You can construct an exception using rb_make_exception
.
This hook may be invoked by a different thread.
[in] | scheduler | Target scheduler. |
[in] | fiber | The fiber to interrupt. |
[in] | exception | The exception to raise in the fiber. |
scheduler.fiber_interrupt
returns. Definition at line 1073 of file scheduler.c.
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 369 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 . |
scheduler.io_close
returns. Definition at line 976 of file scheduler.c.
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 . |
scheduler.io_read
returns. Definition at line 817 of file scheduler.c.
Referenced by 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 . |
scheduler.io_read
returns. Definition at line 952 of file scheduler.c.
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 . |
scheduler.io_write
returns. Definition at line 910 of file scheduler.c.
Referenced by 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 . |
scheduler.io_write
returns. Definition at line 964 of file scheduler.c.
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 . |
scheduler.io_read
returns [-errno, size]
. Definition at line 778 of file scheduler.c.
Referenced by 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 . |
scheduler.io_read
returns. Definition at line 928 of file scheduler.c.
|
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 . |
VALUE
which contains the result and/or errno. Definition at line 49 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. |
int errno
with the value if negative. Definition at line 71 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. |
scheduler.io_select
returns, normally a 3-tuple of arrays of ready objects. Definition at line 725 of file scheduler.c.
Non-blocking version of IO.select
, argv
variant.
Definition at line 734 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_select().
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. |
scheduler.io_wait
returns. Definition at line 690 of file scheduler.c.
Referenced by 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. |
scheduler.io_wait
returns. Definition at line 704 of file scheduler.c.
Referenced by 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. |
scheduler.io_wait
returns. Definition at line 710 of file scheduler.c.
Referenced by 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 . |
scheduler.io_write
returns [-errno, size]
. Definition at line 870 of file scheduler.c.
Referenced by 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 . |
scheduler.io_write
returns. Definition at line 940 of file scheduler.c.
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 . |
scheduler.kernel_sleep
returns. Definition at line 522 of file scheduler.c.
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 |
scheduler.kernel_sleep
returns. Definition at line 528 of file scheduler.c.
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 501 of file scheduler.c.
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 . |
scheduler.process_wait
returns. Definition at line 598 of file scheduler.c.
Referenced by 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. |
scheduler
. Definition at line 419 of file scheduler.c.
Wakes up a fiber previously blocked using rb_fiber_scheduler_block().
This function may be called from a different thread.
[in] | scheduler | Target scheduler. |
[in] | blocker | What was awaited for. |
[in] | fiber | What to unblock. |
scheduler.unblock
returns. Definition at line 641 of file scheduler.c.