Ruby 3.2.1p31 (2023-02-08 revision 31819e82c88c6f8ecfaeb162519bfa26a14b21fd)
Macros | Functions
scheduler.h File Reference

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.
 

Detailed Description

Scheduler APIs.

Author
Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Definition in file scheduler.h.

Macro Definition Documentation

◆ RUBY_FIBER_SCHEDULER_VERSION

#define RUBY_FIBER_SCHEDULER_VERSION   2

Definition at line 26 of file scheduler.h.

Function Documentation

◆ rb_fiber_scheduler_address_resolve()

VALUE rb_fiber_scheduler_address_resolve ( VALUE  scheduler,
VALUE  hostname 
)

Non-blocking DNS lookup.

Parameters
[in]schedulerTarget scheduler.
[in]hostnameA host name to query.
Return values
RUBY_Qundefscheduler doesn't have #address_resolve.
Returns
otherwise What scheduler.address_resolve returns.

Definition at line 635 of file scheduler.c.

Referenced by rb_fiber_scheduler_address_resolve().

◆ rb_fiber_scheduler_block()

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.

Depending on scheduler implementation, this for instance switches to another fiber etc.

Parameters
[in]schedulerTarget scheduler.
[in]blockerWhat blocks the current fiber.
[in]timeoutNumeric timeout.
Returns
What scheduler.block returns.

Definition at line 367 of file scheduler.c.

Referenced by rb_fiber_scheduler_block().

◆ rb_fiber_scheduler_close()

VALUE rb_fiber_scheduler_close ( VALUE  scheduler)

Closes the passed scheduler object.

This expects the scheduler to wait for all fibers. Thus the scheduler's main loop tends to start here.

Parameters
[in]schedulerTarget scheduler.
Returns
What scheduler.close returns.

Definition at line 224 of file scheduler.c.

Referenced by rb_fiber_scheduler_close(), and rb_fiber_scheduler_set().

◆ rb_fiber_scheduler_current()

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.

Return values
RUBY_QnilNo scheduler is in effect.
otherwiseThe scheduler that is in effect, if any.

Definition at line 203 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().

◆ rb_fiber_scheduler_current_for_thread()

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.

Parameters
[in]threadTarget thread.
Exceptions
rb_eTypeError`thread` is not a thread.
Return values
RUBY_QnilNo scheduler is in effect in thread.
otherwiseThe scheduler that is in effect in thread.

Definition at line 208 of file scheduler.c.

Referenced by rb_fiber_scheduler_current_for_thread().

◆ rb_fiber_scheduler_fiber()

VALUE rb_fiber_scheduler_fiber ( VALUE  scheduler,
int  argc,
VALUE argv,
int  kw_splat 
)

Create and schedule a non-blocking fiber.

Definition at line 660 of file scheduler.c.

Referenced by rb_fiber_scheduler_fiber().

◆ rb_fiber_scheduler_get()

VALUE rb_fiber_scheduler_get ( void  )

Queries the current scheduler of the current thread that is calling this function.

Return values
RUBY_QnilNo scheduler has been set so far to this thread (which is the default).
otherwiseThe 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().

◆ rb_fiber_scheduler_io_close()

VALUE rb_fiber_scheduler_io_close ( VALUE  scheduler,
VALUE  io 
)

Non-blocking close the given IO.

Parameters
[in]schedulerTarget scheduler.
[in]ioAn io object to close.
Return values
RUBY_Qundefscheduler doesn't have #io_close.
Returns
otherwise What scheduler.io_close returns.

Definition at line 595 of file scheduler.c.

Referenced by rb_fiber_scheduler_io_close().

◆ rb_fiber_scheduler_io_pread()

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.

Parameters
[in]schedulerTarget scheduler.
[out]ioAn io object to read from.
[in]fromThe offset in the given IO to read the data from.
[out]bufferThe buffer to read the data to.
[in]lengthRequested number of bytes to read.
[in]offsetThe offset in the buffer to read to.
Return values
RUBY_Qundefscheduler doesn't have #io_read.
Returns
otherwise What scheduler.io_read returns.

Definition at line 505 of file scheduler.c.

Referenced by rb_fiber_scheduler_io_pread().

◆ rb_fiber_scheduler_io_pwrite()

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.

Parameters
[in]schedulerTarget scheduler.
[out]ioAn io object to write to.
[in]fromThe offset in the given IO to write the data to.
[in]bufferThe buffer to write the data from.
[in]lengthNumber of bytes to write.
[in]offsetThe offset in the buffer to write from.
Return values
RUBY_Qundefscheduler doesn't have #io_write.
Returns
otherwise What scheduler.io_write returns.

Definition at line 559 of file scheduler.c.

Referenced by rb_fiber_scheduler_io_pwrite().

◆ rb_fiber_scheduler_io_read()

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.

Parameters
[in]schedulerTarget scheduler.
[out]ioAn io object to read from.
[out]bufferReturn buffer.
[in]lengthRequested number of bytes to read.
[in]offsetThe offset in the buffer to read to.
Return values
RUBY_Qundefscheduler doesn't have #io_read.
Returns
otherwise What scheduler.io_read returns [-errno, size].

Definition at line 487 of file scheduler.c.

Referenced by rb_fiber_scheduler_io_read(), and rb_fiber_scheduler_io_read_memory().

◆ 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.

Parameters
[in]schedulerTarget scheduler.
[out]ioAn io object to read from.
[out]bufferReturn buffer.
[in]sizeSize of the return buffer.
[in]lengthRequested number of bytes to read.
Return values
RUBY_Qundefscheduler doesn't have #io_read.
Returns
otherwise What scheduler.io_read returns.

Definition at line 569 of file scheduler.c.

Referenced by rb_fiber_scheduler_io_read_memory().

◆ rb_fiber_scheduler_io_result()

static VALUE rb_fiber_scheduler_io_result ( ssize_t  result,
int  error 
)
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.

Parameters
[in]resultThe result of the system call.
[in]errorThe value of errno.
Returns
A VALUE which contains the result and/or errno.

Definition at line 48 of file scheduler.h.

◆ rb_fiber_scheduler_io_result_apply()

static ssize_t rb_fiber_scheduler_io_result_apply ( VALUE  result)
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.

Parameters
[in]resultThe VALUE which contains an errno and/or result size.
Postcondition
Updates int errno with the value if negative.
Returns
The original result of the system call.

Definition at line 70 of file scheduler.h.

◆ rb_fiber_scheduler_io_select()

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.

Parameters
[in]schedulerTarget scheduler.
[in]readablesAn array of readable objects.
[in]writablesAn array of writable objects.
[in]exceptablesAn array of objects that might encounter exceptional conditions.
[in]timeoutNumeric timeout or nil.
Returns
What scheduler.io_select returns, normally a 3-tuple of arrays of ready objects.

Definition at line 440 of file scheduler.c.

Referenced by rb_fiber_scheduler_io_select().

◆ rb_fiber_scheduler_io_selectv()

VALUE rb_fiber_scheduler_io_selectv ( VALUE  scheduler,
int  argc,
VALUE argv 
)

Non-blocking version of IO.select, argv variant.

Definition at line 449 of file scheduler.c.

Referenced by rb_fiber_scheduler_io_select(), and rb_fiber_scheduler_io_selectv().

◆ rb_fiber_scheduler_io_wait()

VALUE rb_fiber_scheduler_io_wait ( VALUE  scheduler,
VALUE  io,
VALUE  events,
VALUE  timeout 
)

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.

Parameters
[in]schedulerTarget scheduler.
[in]ioAn io object to wait.
[in]eventsAn integer set of interests.
[in]timeoutNumeric timeout.
Returns
What scheduler.io_wait returns.

Definition at line 413 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().

◆ rb_fiber_scheduler_io_wait_readable()

VALUE rb_fiber_scheduler_io_wait_readable ( VALUE  scheduler,
VALUE  io 
)

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.

Parameters
[in]schedulerTarget scheduler.
[in]ioAn io object to wait.
Returns
What scheduler.io_wait returns.

Definition at line 419 of file scheduler.c.

Referenced by rb_fiber_scheduler_io_wait_readable(), and rb_io_wait_readable().

◆ rb_fiber_scheduler_io_wait_writable()

VALUE rb_fiber_scheduler_io_wait_writable ( VALUE  scheduler,
VALUE  io 
)

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.

Parameters
[in]schedulerTarget scheduler.
[in]ioAn io object to wait.
Returns
What scheduler.io_wait returns.

Definition at line 425 of file scheduler.c.

Referenced by rb_fiber_scheduler_io_wait_writable(), and rb_io_wait_writable().

◆ rb_fiber_scheduler_io_write()

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.

Parameters
[in]schedulerTarget scheduler.
[out]ioAn io object to write to.
[in]bufferWhat to write.
[in]lengthNumber of bytes to write.
[in]offsetThe offset in the buffer to write from.
Return values
RUBY_Qundefscheduler doesn't have #io_write.
Returns
otherwise What scheduler.io_write returns [-errno, size].

Definition at line 542 of file scheduler.c.

Referenced by rb_fiber_scheduler_io_write(), and rb_fiber_scheduler_io_write_memory().

◆ 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.

Parameters
[in]schedulerTarget scheduler.
[out]ioAn io object to write to.
[in]bufferWhat to write.
[in]sizeSize of the buffer.
[in]lengthNumber of bytes to write.
Return values
RUBY_Qundefscheduler doesn't have #io_write.
Returns
otherwise What scheduler.io_write returns.

Definition at line 582 of file scheduler.c.

Referenced by rb_fiber_scheduler_io_write_memory().

◆ rb_fiber_scheduler_kernel_sleep()

VALUE rb_fiber_scheduler_kernel_sleep ( VALUE  scheduler,
VALUE  duration 
)

Non-blocking sleep.

Depending on scheduler implementation, this for instance switches to another fiber etc.

Parameters
[in]schedulerTarget scheduler.
[in]durationPassed as-is to scheduler.kernel_sleep.
Returns
What scheduler.kernel_sleep returns.

Definition at line 267 of file scheduler.c.

Referenced by rb_fiber_scheduler_kernel_sleep(), and rb_mutex_sleep().

◆ rb_fiber_scheduler_kernel_sleepv()

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.

Parameters
[in]schedulerTarget scheduler.
[in]argcNumber of objects of argv.
[in]argvPassed as-is to scheduler.kernel_sleep
Returns
What scheduler.kernel_sleep returns.

Definition at line 273 of file scheduler.c.

Referenced by rb_fiber_scheduler_kernel_sleepv().

◆ rb_fiber_scheduler_make_timeout()

VALUE rb_fiber_scheduler_make_timeout ( struct timeval timeout)

Converts the passed timeout to an expression that rb_fiber_scheduler_block() etc.

expects.

Parameters
[in]timeoutA duration (can be NULL).
Return values
RUBY_QnilNo timeout (blocks indefinitely).
otherwiseA timeout object.

Definition at line 246 of file scheduler.c.

Referenced by rb_fiber_scheduler_make_timeout().

◆ rb_fiber_scheduler_process_wait()

VALUE rb_fiber_scheduler_process_wait ( VALUE  scheduler,
rb_pid_t  pid,
int  flags 
)

Non-blocking waitpid.

Depending on scheduler implementation, this for instance switches to another fiber etc.

Parameters
[in]schedulerTarget scheduler.
[in]pidProcess ID to wait.
[in]flagsWait flags, e.g. WUNTRACED.
Returns
What scheduler.process_wait returns.

Definition at line 343 of file scheduler.c.

Referenced by rb_fiber_scheduler_process_wait().

◆ rb_fiber_scheduler_set()

VALUE rb_fiber_scheduler_set ( VALUE  scheduler)

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.

Parameters
[in]schedulerThe scheduler to set.
Exceptions
rb_eArgError`scheduler` does not conform the interface.
Postcondition
Current thread's scheduler is scheduler.

Definition at line 165 of file scheduler.c.

Referenced by rb_fiber_scheduler_set().

◆ rb_fiber_scheduler_unblock()

VALUE rb_fiber_scheduler_unblock ( VALUE  scheduler,
VALUE  blocker,
VALUE  fiber 
)

Wakes up a fiber previously blocked using rb_fiber_scheduler_block().

Parameters
[in]schedulerTarget scheduler.
[in]blockerWhat was awaited for.
[in]fiberWhat to unblock.
Returns
What scheduler.unblock returns.

Definition at line 386 of file scheduler.c.

Referenced by rb_fiber_scheduler_unblock().