Ruby
3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
|
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_region_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 . More... | |
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 . More... | |
VALUE | rb_fiber_scheduler_get (void) |
Queries the current scheduler of the current thread that is calling this function. More... | |
VALUE | rb_fiber_scheduler_set (VALUE scheduler) |
Destructively assigns the passed scheduler to that of the current thread that is calling this function. More... | |
VALUE | rb_fiber_scheduler_current (void) |
Identical to rb_fiber_scheduler_get(), except it also returns RUBY_Qnil in case of a blocking fiber. More... | |
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. More... | |
VALUE | rb_fiber_scheduler_make_timeout (struct timeval *timeout) |
Converts the passed timeout to an expression that rb_fiber_scheduler_block() etc. More... | |
VALUE | rb_fiber_scheduler_close (VALUE scheduler) |
Closes the passed scheduler object. More... | |
VALUE | rb_fiber_scheduler_kernel_sleep (VALUE scheduler, VALUE duration) |
Non-blocking sleep . More... | |
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. More... | |
VALUE | rb_fiber_scheduler_process_wait (VALUE scheduler, rb_pid_t pid, int flags) |
Non-blocking waitpid . More... | |
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 . More... | |
VALUE | rb_fiber_scheduler_unblock (VALUE scheduler, VALUE blocker, VALUE fiber) |
Wakes up a fiber previously blocked using rb_fiber_scheduler_block(). More... | |
VALUE | rb_fiber_scheduler_io_wait (VALUE scheduler, VALUE io, VALUE events, VALUE timeout) |
Non-blocking version of rb_io_wait(). More... | |
VALUE | rb_fiber_scheduler_io_wait_readable (VALUE scheduler, VALUE io) |
Non-blocking wait until the passed IO is ready for reading. More... | |
VALUE | rb_fiber_scheduler_io_wait_writable (VALUE scheduler, VALUE io) |
Non-blocking wait until the passed IO is ready for writing. More... | |
VALUE | rb_fiber_scheduler_io_select (VALUE scheduler, VALUE readables, VALUE writables, VALUE exceptables, VALUE timeout) |
Non-blocking version of IO.select . More... | |
VALUE | rb_fiber_scheduler_io_selectv (VALUE scheduler, int argc, VALUE *argv) |
Non-blocking version of IO.select , argv variant. More... | |
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. More... | |
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. More... | |
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. More... | |
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. More... | |
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. More... | |
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. More... | |
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. More... | |
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. More... | |
VALUE | rb_fiber_scheduler_io_close (VALUE scheduler, VALUE io) |
Non-blocking close the given IO. More... | |
VALUE | rb_fiber_scheduler_address_resolve (VALUE scheduler, VALUE hostname) |
Non-blocking DNS lookup. More... | |
VALUE | rb_fiber_scheduler_blocking_region (VALUE scheduler, void *(*function)(void *), void *data, rb_unblock_function_t *unblock_function, void *data2, int flags, struct rb_fiber_scheduler_blocking_region_state *state) |
Defer the execution of the passed function to the scheduler. More... | |
VALUE | rb_fiber_scheduler_fiber (VALUE scheduler, int argc, VALUE *argv, int kw_splat) |
Create and schedule a non-blocking fiber. More... | |
Scheduler APIs.
Definition in 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 694 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 390 of file scheduler.c.
VALUE rb_fiber_scheduler_blocking_region | ( | VALUE | scheduler, |
void *(*)(void *) | function, | ||
void * | data, | ||
rb_unblock_function_t * | unblock_function, | ||
void * | data2, | ||
int | flags, | ||
struct rb_fiber_scheduler_blocking_region_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_region . |
scheduler.blocking_region
returns. Definition at line 743 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 247 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 226 of file scheduler.c.
Referenced by rb_io_wait(), rb_io_wait_readable(), rb_io_wait_writable(), rb_mutex_sleep(), 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 231 of file scheduler.c.
Create and schedule a non-blocking fiber.
Definition at line 775 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 141 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 654 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 533 of file scheduler.c.
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 630 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 596 of file scheduler.c.
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 642 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 509 of file scheduler.c.
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 606 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 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. |
int errno
with the value if negative. 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. |
scheduler.io_select
returns, normally a 3-tuple of arrays of ready objects. Definition at line 463 of file scheduler.c.
Non-blocking version of IO.select
, argv
variant.
Definition at line 472 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 436 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 442 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 448 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 571 of file scheduler.c.
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 618 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 290 of file scheduler.c.
Referenced by rb_mutex_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 |
scheduler.kernel_sleep
returns. Definition at line 296 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 269 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 366 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 187 of file scheduler.c.
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. |
scheduler.unblock
returns. Definition at line 409 of file scheduler.c.