Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Data Structures | Macros | Functions
scheduler.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

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"
Include dependency graph for scheduler.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  rb_fiber_scheduler_blocking_operation_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_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. More...
 
VALUE rb_fiber_scheduler_fiber (VALUE scheduler, int argc, VALUE *argv, int kw_splat)
 Create and schedule a non-blocking fiber. More...
 

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.

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 694 of file scheduler.c.

◆ 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 390 of file scheduler.c.

◆ rb_fiber_scheduler_blocking_operation_wait()

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.

Parameters
[in]schedulerTarget scheduler.
[in]functionThe function to run.
[in]dataThe data to pass to the function.
[in]unblock_functionThe unblock function to use to interrupt the operation.
[in]data2The data to pass to the unblock function.
[in]flagsFlags passed to rb_nogvl.
[out]stateThe result and errno of the operation.
Return values
RUBY_Qundefscheduler doesn't have #blocking_operation_wait.
Returns
otherwise What scheduler.blocking_operation_wait returns.

Definition at line 743 of file scheduler.c.

Referenced by rb_nogvl().

◆ 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 247 of file scheduler.c.

◆ 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 226 of file scheduler.c.

Referenced by rb_io_wait(), rb_io_wait_readable(), rb_io_wait_writable(), rb_nogvl(), and rb_process_status_wait().

◆ 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_eTypeErrorthread 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 231 of file scheduler.c.

◆ 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 775 of file scheduler.c.

◆ 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 141 of file scheduler.c.

◆ 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 654 of file scheduler.c.

◆ 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.
[in]ioAn io object to read from.
[in]fromThe offset to read from.
[in]bufferThe buffer to read to.
[in]lengthThe minimum 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 533 of file scheduler.c.

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

Parameters
[in]schedulerTarget scheduler.
[in]ioAn io object to read from.
[in]fromThe offset to read from.
[in]baseThe memory to read to.
[in]sizeSize of the memory.
[in]lengthThe minimum number of bytes to read.
Return values
RUBY_Qundefscheduler doesn't have #io_read.
Returns
otherwise What scheduler.io_read returns.

Definition at line 630 of file scheduler.c.

◆ 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.
[in]ioAn io object to write to.
[in]fromThe offset to write to.
[in]bufferThe buffer to write from.
[in]lengthThe minimum number 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 596 of file scheduler.c.

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

Parameters
[in]schedulerTarget scheduler.
[in]ioAn io object to write to.
[in]fromThe offset to write from.
[in]baseThe memory to write from.
[in]sizeSize of the memory.
[in]lengthThe minimum number of bytes to write.
Return values
RUBY_Qundefscheduler doesn't have #io_write.
Returns
otherwise What scheduler.io_write returns.

Definition at line 642 of file scheduler.c.

◆ 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.
[in]ioAn io object to read from.
[in]bufferThe buffer to read to.
[in]lengthThe minimum number of bytes to read.
[in]offsetThe offset in the buffer to read from.
Return values
RUBY_Qundefscheduler doesn't have #io_read.
Returns
otherwise What scheduler.io_read returns [-errno, size].

Definition at line 509 of file scheduler.c.

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

Parameters
[in]schedulerTarget scheduler.
[in]ioAn io object to read from.
[in]baseThe memory to read to.
[in]sizeSize of the memory.
[in]lengthThe minimum number of bytes to read.
Return values
RUBY_Qundefscheduler doesn't have #io_read.
Returns
otherwise What scheduler.io_read returns.

Definition at line 606 of file scheduler.c.

◆ 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 463 of file scheduler.c.

◆ 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 472 of file scheduler.c.

Referenced by rb_fiber_scheduler_io_select().

◆ 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 436 of file scheduler.c.

Referenced by 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 442 of file scheduler.c.

Referenced by 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 448 of file scheduler.c.

Referenced by 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.
[in]ioAn io object to write to.
[in]bufferThe buffer to write from.
[in]lengthThe minimum number 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 571 of file scheduler.c.

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

Parameters
[in]schedulerTarget scheduler.
[in]ioAn io object to write to.
[in]baseThe memory to write from.
[in]sizeSize of the memory.
[in]lengthThe minimum number of bytes to write.
Return values
RUBY_Qundefscheduler doesn't have #io_write.
Returns
otherwise What scheduler.io_write returns.

Definition at line 618 of file scheduler.c.

◆ 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 290 of file scheduler.c.

◆ 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 296 of file scheduler.c.

◆ 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 269 of file scheduler.c.

◆ 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 366 of file scheduler.c.

Referenced by rb_process_status_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::Scheduler interface. Its implementation is up to the user.

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

Definition at line 187 of file scheduler.c.

◆ 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 409 of file scheduler.c.