Ruby  3.1.4p223 (2023-03-30 revision HEAD)
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.

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

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 
)

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

◆ rb_fiber_scheduler_block()

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.

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

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

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

Referenced by 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_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 131 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 60 of file scheduler.c.

◆ rb_fiber_scheduler_io_close()

VALUE rb_fiber_scheduler_io_close ( VALUE  scheduler,
VALUE  io 
)

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

◆ rb_fiber_scheduler_io_pread()

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.

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 given IO to read the data from.
Return values
RUBY_Qundefscheduler doesn't have #io_read.
Returns
otherwise What scheduler.io_read returns.

Definition at line 245 of file scheduler.c.

◆ rb_fiber_scheduler_io_pwrite()

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.

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 given IO to write the data to.
Return values
RUBY_Qundefscheduler doesn't have #io_write.
Returns
otherwise What scheduler.io_write returns.

Definition at line 265 of file scheduler.c.

◆ rb_fiber_scheduler_io_read()

VALUE rb_fiber_scheduler_io_read ( VALUE  scheduler,
VALUE  io,
VALUE  buffer,
size_t  length 
)

Nonblocking 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.
Return values
RUBY_Qundefscheduler doesn't have #io_read.
Returns
otherwise What scheduler.io_read returns [-errno, size].

Definition at line 235 of file scheduler.c.

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

Nonblocking read from the passed IO using a native buffer.

Parameters
[in]schedulerTarget scheduler.
[out]ioAn io object to read from.
[out]bufferReturn 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 275 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 46 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 66 of file scheduler.h.

◆ rb_fiber_scheduler_io_wait()

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

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.

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 217 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 
)

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.

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

Definition at line 223 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 
)

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.

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

Definition at line 229 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 
)

Nonblocking 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.
Return values
RUBY_Qundefscheduler doesn't have #io_write.
Returns
otherwise What scheduler.io_write returns [-errno, size].

Definition at line 255 of file scheduler.c.

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

Nonblocking 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]lengthNumber of bytes to write.
Return values
RUBY_Qundefscheduler doesn't have #io_write.
Returns
otherwise What scheduler.io_write returns.

Definition at line 288 of file scheduler.c.

◆ rb_fiber_scheduler_kernel_sleep()

VALUE rb_fiber_scheduler_kernel_sleep ( VALUE  scheduler,
VALUE  duration 
)

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

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

◆ rb_fiber_scheduler_process_wait()

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

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

◆ 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_eArgErrorscheduler does not conform the interface.
Postcondition
Current thread's scheduler is scheduler.

Definition at line 91 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 209 of file scheduler.c.