|
Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)
|
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.
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 *buffer, 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 *buffer, size_t size, size_t length) |
| Non-blocking write 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_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. |
scheduler.address_resolve returns. Definition at line 651 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. |
scheduler.block returns. Definition at line 383 of file scheduler.c.
Referenced by rb_fiber_scheduler_block().
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 240 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 219 of file scheduler.c.
Referenced by rb_fiber_scheduler_current(), rb_io_wait(), rb_io_wait_readable(), rb_io_wait_writable(), and rb_mutex_sleep().
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 224 of file scheduler.c.
Referenced by rb_fiber_scheduler_current_for_thread().
Create and schedule a non-blocking fiber.
Definition at line 676 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 134 of file scheduler.c.
Referenced by rb_fiber_scheduler_get().
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 611 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. |
| [out] | io | An io object to read from. |
| [in] | from | The offset in the given IO to read the data from. |
| [out] | buffer | The buffer to read the data to. |
| [in] | length | Requested 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 520 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_pread().
| 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. |
| [out] | io | An io object to write to. |
| [in] | from | The offset in the given IO to write the data to. |
| [in] | buffer | The buffer to write the data from. |
| [in] | length | 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 575 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_pwrite().
| 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. |
| [out] | io | An io object to read from. |
| [out] | buffer | Return buffer. |
| [in] | length | Requested 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 [-errno, size]. Definition at line 502 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 * | buffer, | ||
| size_t | size, | ||
| size_t | length ) |
Non-blocking read from the passed IO using a native buffer.
| [in] | scheduler | Target scheduler. |
| [out] | io | An io object to read from. |
| [out] | buffer | Return buffer. |
| [in] | size | Size of the return buffer. |
| [in] | length | Requested number of bytes to read. |
| RUBY_Qundef | scheduler doesn't have #io_read. |
scheduler.io_read returns. Definition at line 585 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. |
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 456 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_select().
Non-blocking version of IO.select, argv variant.
Definition at line 465 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. |
scheduler.io_wait returns. Definition at line 429 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. |
scheduler.io_wait returns. Definition at line 435 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. |
scheduler.io_wait returns. Definition at line 441 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. |
| [out] | io | An io object to write to. |
| [in] | buffer | What to write. |
| [in] | length | 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 558 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 * | buffer, | ||
| size_t | size, | ||
| size_t | length ) |
Non-blocking write to the passed IO using a native buffer.
| [in] | scheduler | Target scheduler. |
| [out] | io | An io object to write to. |
| [in] | buffer | What to write. |
| [in] | size | Size of the buffer. |
| [in] | length | Number of bytes to write. |
| RUBY_Qundef | scheduler doesn't have #io_write. |
scheduler.io_write returns. Definition at line 598 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. |
scheduler.kernel_sleep returns. Definition at line 283 of file scheduler.c.
Referenced by rb_fiber_scheduler_kernel_sleep(), and 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 289 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 262 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. |
scheduler.process_wait returns. Definition at line 359 of file scheduler.c.
Referenced by rb_fiber_scheduler_process_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::SchedulerInterface. 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 180 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. |
scheduler.unblock returns. Definition at line 402 of file scheduler.c.
Referenced by rb_fiber_scheduler_unblock().