Ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e0ba6b95ab71a441357ed5484e33498)
|
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.
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) |
Nonblocking 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) |
Nonblocking waitpid . More... | |
VALUE | rb_fiber_scheduler_block (VALUE scheduler, VALUE blocker, VALUE timeout) |
Nonblocking 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) |
Nonblocking version of rb_io_wait(). More... | |
VALUE | rb_fiber_scheduler_io_wait_readable (VALUE scheduler, VALUE io) |
Nonblocking wait until the passed IO is ready for reading. More... | |
VALUE | rb_fiber_scheduler_io_wait_writable (VALUE scheduler, VALUE io) |
Nonblocking wait until the passed IO is ready for writing. More... | |
VALUE | rb_fiber_scheduler_io_read (VALUE scheduler, VALUE io, VALUE buffer, size_t length) |
Nonblocking read from the passed IO. More... | |
VALUE | rb_fiber_scheduler_io_write (VALUE scheduler, VALUE io, VALUE buffer, size_t length) |
Nonblocking write to the passed IO. More... | |
VALUE | rb_fiber_scheduler_io_pread (VALUE scheduler, VALUE io, VALUE buffer, size_t length, off_t offset) |
Nonblocking read from the passed IO at the specified offset. More... | |
VALUE | rb_fiber_scheduler_io_pwrite (VALUE scheduler, VALUE io, VALUE buffer, size_t length, off_t offset) |
Nonblocking write to the passed IO at the specified offset. More... | |
VALUE | rb_fiber_scheduler_io_read_memory (VALUE scheduler, VALUE io, void *buffer, size_t size, size_t length) |
Nonblocking read from the passed IO using a native buffer. More... | |
VALUE | rb_fiber_scheduler_io_write_memory (VALUE scheduler, VALUE io, const void *buffer, size_t size, size_t length) |
Nonblocking write to the passed IO using a native buffer. More... | |
VALUE | rb_fiber_scheduler_io_close (VALUE scheduler, VALUE io) |
Nonblocking close the given IO. More... | |
VALUE | rb_fiber_scheduler_address_resolve (VALUE scheduler, VALUE hostname) |
Nonblocking DNS lookup. More... | |
Scheduler APIs.
Definition in file scheduler.h.
Nonblocking 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 309 of file scheduler.c.
Nonblocking 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 203 of file scheduler.c.
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 137 of file scheduler.c.
Referenced by rb_fiber_scheduler_set().
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 126 of file scheduler.c.
Referenced by 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 131 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 60 of file scheduler.c.
Nonblocking 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 301 of file scheduler.c.
VALUE rb_fiber_scheduler_io_pread | ( | VALUE | scheduler, |
VALUE | io, | ||
VALUE | buffer, | ||
size_t | length, | ||
off_t | offset | ||
) |
Nonblocking read from the passed IO at the specified offset.
[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 given IO to read the data from. |
RUBY_Qundef | scheduler doesn't have #io_read . |
scheduler.io_read
returns. Definition at line 245 of file scheduler.c.
VALUE rb_fiber_scheduler_io_pwrite | ( | VALUE | scheduler, |
VALUE | io, | ||
VALUE | buffer, | ||
size_t | length, | ||
off_t | offset | ||
) |
Nonblocking write to the passed IO at the specified offset.
[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 given IO to write the data to. |
RUBY_Qundef | scheduler doesn't have #io_write . |
scheduler.io_write
returns. Definition at line 265 of file scheduler.c.
Nonblocking 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. |
RUBY_Qundef | scheduler doesn't have #io_read . |
scheduler.io_read
returns [-errno, size]
. Definition at line 235 of file scheduler.c.
VALUE rb_fiber_scheduler_io_read_memory | ( | VALUE | scheduler, |
VALUE | io, | ||
void * | buffer, | ||
size_t | size, | ||
size_t | length | ||
) |
Nonblocking 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] | length | Requested number of bytes to read. |
RUBY_Qundef | scheduler doesn't have #io_read . |
scheduler.io_read
returns. Definition at line 275 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 46 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 66 of file scheduler.h.
Nonblocking 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 217 of file scheduler.c.
Referenced by rb_fiber_scheduler_io_wait_readable(), rb_fiber_scheduler_io_wait_writable(), and rb_io_wait().
Nonblocking 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 223 of file scheduler.c.
Referenced by rb_io_wait_readable().
Nonblocking 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 229 of file scheduler.c.
Referenced by rb_io_wait_writable().
Nonblocking 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. |
RUBY_Qundef | scheduler doesn't have #io_write . |
scheduler.io_write
returns [-errno, size]
. Definition at line 255 of file scheduler.c.
VALUE rb_fiber_scheduler_io_write_memory | ( | VALUE | scheduler, |
VALUE | io, | ||
const void * | buffer, | ||
size_t | size, | ||
size_t | length | ||
) |
Nonblocking 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] | length | Number of bytes to write. |
RUBY_Qundef | scheduler doesn't have #io_write . |
scheduler.io_write
returns. Definition at line 288 of file scheduler.c.
Nonblocking 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 163 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 169 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 153 of file scheduler.c.
Nonblocking 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 193 of file scheduler.c.
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 91 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 209 of file scheduler.c.