Ruby: include/ruby/fiber/scheduler.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

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

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

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] | scheduler | Target scheduler.
  [in] | hostname | A host name to query.

Return values

  RUBY_Qundef | `scheduler` doesn't have `#address_resolve`.

Returns
  otherwise What `scheduler.address_resolve` returns.

Definition at line 651 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] | scheduler | Target scheduler.
  [in] | blocker | What blocks the current fiber.
  [in] | timeout | Numeric timeout.

Returns
  What `scheduler.block` returns.

Definition at line 383 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] | scheduler | Target scheduler.

Returns
  What `scheduler.close` returns.

Definition at line 240 of file scheduler.c.

Referenced by rb_fiber_scheduler_close().

## ◆ 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_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().

## ◆ 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] | thread | Target thread.

Exceptions

  rb_eTypeError | `thread` is not a thread.

Return values

  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().

## ◆ 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 676 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_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().

## ◆ rb_fiber_scheduler_io_close()

VALUE rb_fiber_scheduler_io_close | ( | VALUE | scheduler,
|  | VALUE | io )

Non-blocking close the given IO.

Parameters

  [in] | scheduler | Target scheduler.
  [in] | io | An io object to close.

Return values

  RUBY_Qundef | `scheduler` doesn't have `#io_close`.

Returns
  otherwise What `scheduler.io_close` returns.

Definition at line 611 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] | 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.

Return values

  RUBY_Qundef | `scheduler` doesn't have `#io_read`.

Returns
  otherwise What `scheduler.io_read` returns.

Definition at line 520 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] | 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.

Return values

  RUBY_Qundef | `scheduler` doesn't have `#io_write`.

Returns
  otherwise What `scheduler.io_write` returns.

Definition at line 575 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] | 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.

Return values

  RUBY_Qundef | `scheduler` doesn't have `#io_read`.

Returns
  otherwise What `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().

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

Return values

  RUBY_Qundef | `scheduler` doesn't have `#io_read`.

Returns
  otherwise What `scheduler.io_read` returns.

Definition at line 585 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] | result | The result of the system call.
  [in] | error | The 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] | result | The `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] | 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.

Returns
  What `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().

## ◆ 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 465 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] | scheduler | Target scheduler.
  [in] | io | An io object to wait.
  [in] | events | An integer set of interests.
  [in] | timeout | Numeric timeout.

Returns
  What `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().

## ◆ 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] | scheduler | Target scheduler.
  [in] | io | An io object to wait.

Returns
  What `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().

## ◆ 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] | scheduler | Target scheduler.
  [in] | io | An io object to wait.

Returns
  What `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().

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

Return values

  RUBY_Qundef | `scheduler` doesn't have `#io_write`.

Returns
  otherwise What `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().

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

Return values

  RUBY_Qundef | `scheduler` doesn't have `#io_write`.

Returns
  otherwise What `scheduler.io_write` returns.

Definition at line 598 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] | scheduler | Target scheduler.
  [in] | duration | Passed as-is to `scheduler.kernel_sleep`.

Returns
  What `scheduler.kernel_sleep` returns.

Definition at line 283 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] | scheduler | Target scheduler.
  [in] | argc | Number of objects of `argv`.
  [in] | argv | Passed as-is to `scheduler.kernel_sleep`

Returns
  What `scheduler.kernel_sleep` returns.

Definition at line 289 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] | timeout | A duration (can be `NULL`).

Return values

  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().

## ◆ 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] | scheduler | Target scheduler.
  [in] | pid | Process ID to wait.
  [in] | flags | Wait flags, e.g. `WUNTRACED`.

Returns
  What `scheduler.process_wait` returns.

Definition at line 359 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] | scheduler | The scheduler to set.

Exceptions

  rb_eArgError | `scheduler` does not conform the interface.

Postcondition
  Current thread's scheduler is `scheduler`.

Definition at line 180 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] | scheduler | Target scheduler.
  [in] | blocker | What was awaited for.
  [in] | fiber | What to unblock.

Returns
  What `scheduler.unblock` returns.

Definition at line 402 of file scheduler.c.

Referenced by rb_fiber_scheduler_unblock().