class Fiber::Scheduler

This is not an existing class, but documentation of the interface that Scheduler object should comply to in order to be used as argument to Fiber.scheduler and handle non-blocking fibers. See also the “Non-blocking fibers” section in Fiber class docs for explanations of some concepts.

Scheduler’s behavior and usage are expected to be as follows:

When the execution in the non-blocking Fiber reaches some blocking operation (like sleep, wait for a process, or a non-ready I/O), it calls some of the scheduler’s hook methods, listed below.
Scheduler somehow registers what the current fiber is waiting on, and yields control to other fibers with Fiber.yield (so the fiber would be suspended while expecting its wait to end, and other fibers in the same thread can perform)
At the end of the current thread execution, the scheduler’s method #scheduler_close is called
The scheduler runs into a wait loop, checking all the blocked fibers (which it has registered on hook calls) and resuming them when the awaited resource is ready (e.g. I/O ready or sleep time elapsed).

This way concurrent execution will be achieved transparently for every individual Fiber’s code.

Scheduler implementations are provided by gems, like Async.

Hook methods are:

io_wait, io_read, io_write, io_pread, io_pwrite io_select, and io_close
process_wait
kernel_sleep
timeout_after
address_resolve
block and unblock
blocking_operation_wait
fiber_interrupt
yield
(the list is expanded as Ruby developers make more methods having non-blocking calls)

The block, unblock, kernel_sleep, io_wait, and fiber_interrupt hooks are mandatory. Other hooks are optional unless specified otherwise.

It is also strongly recommended that the scheduler implements the fiber method, which is delegated to by Fiber.schedule.

Sample toy implementation of the scheduler can be found in Ruby’s code, in test/fiber/scheduler.rb

Public Instance Methods

address_resolve(hostname) → array_of_strings or nil

Source

VALUE
rb_fiber_scheduler_address_resolve(VALUE scheduler, VALUE hostname)
{
    VALUE arguments[] = {
        hostname
    };

    return rb_check_funcall(scheduler, id_address_resolve, 1, arguments);
}

Invoked by any method that performs a non-reverse DNS lookup. The most notable method is Addrinfo.getaddrinfo, but there are many other.

The method is expected to return an array of strings corresponding to ip addresses the hostname is resolved to, or nil if it can not be resolved.

Fairly exhaustive list of all possible call-sites:

block(blocker, timeout = nil)

Source

VALUE
rb_fiber_scheduler_block(VALUE scheduler, VALUE blocker, VALUE timeout)
{
    return rb_funcall(scheduler, id_block, 2, blocker, timeout);
}

Invoked by methods like Thread.join, and by Thread::Mutex, to signify that current Fiber is blocked until further notice (e.g. unblock) or until timeout has elapsed.

blocker is what we are waiting on, informational only (for debugging and logging). There are no guarantee about its value.

Expected to return boolean, specifying whether the blocking operation was successful or not.

blocking_operation_wait(blocking_operation)

Source

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)
{
    // Check if scheduler supports blocking_operation_wait before creating the object
    if (!rb_respond_to(scheduler, id_blocking_operation_wait)) {
        return Qundef;
    }

    // Create a new BlockingOperation with the blocking operation
    VALUE blocking_operation = rb_fiber_scheduler_blocking_operation_new(function, data, unblock_function, data2, flags, state);

    VALUE result = rb_funcall(scheduler, id_blocking_operation_wait, 1, blocking_operation);

    // Get the operation data to check if it was executed
    rb_fiber_scheduler_blocking_operation_t *operation = get_blocking_operation(blocking_operation);
    rb_atomic_t current_status = RUBY_ATOMIC_LOAD(operation->status);

    // Invalidate the operation now that we're done with it
    operation->function = NULL;
    operation->state = NULL;
    operation->data = NULL;
    operation->data2 = NULL;
    operation->unblock_function = NULL;

    // Ensure that the blocking operation remains visible until this point:
    RB_GC_GUARD(blocking_operation);

    // If the blocking operation was never executed, return Qundef to signal the caller to use rb_nogvl instead
    if (current_status == RB_FIBER_SCHEDULER_BLOCKING_OPERATION_STATUS_QUEUED) {
        return Qundef;
    }

    return result;
}

Invoked by Ruby’s core methods to run a blocking operation in a non-blocking way. The blocking_operation is an opaque object that encapsulates the blocking operation and responds to a #call method without any arguments.

If the scheduler doesn’t implement this method, or if the scheduler doesn’t execute the blocking operation, Ruby will fall back to the non-scheduler implementation.

Minimal suggested implementation is:

def blocking_operation_wait(blocking_operation)
  Thread.new { blocking_operation.call }.join
end

close ()

Source

VALUE
rb_fiber_scheduler_close(VALUE scheduler)
{
    RUBY_ASSERT(ruby_thread_has_gvl_p());

    VALUE result;

    // The reason for calling `scheduler_close` before calling `close` is for
    // legacy schedulers which implement `close` and expect the user to call
    // it. Subsequently, that method would call `Fiber.set_scheduler(nil)`
    // which should call `scheduler_close`. If it were to call `close`, it
    // would create an infinite loop.

    result = rb_check_funcall(scheduler, id_scheduler_close, 0, NULL);
    if (!UNDEF_P(result)) return result;

    result = rb_check_funcall(scheduler, id_close, 0, NULL);
    if (!UNDEF_P(result)) return result;

    return Qnil;
}

Called when the current thread exits. The scheduler is expected to implement this method in order to allow all waiting fibers to finalize their execution.

The suggested pattern is to implement the main event loop in the close method.

fiber(&block)

Source

VALUE
rb_fiber_scheduler_fiber(VALUE scheduler, int argc, VALUE *argv, int kw_splat)
{
    return rb_funcall_passing_block_kw(scheduler, id_fiber_schedule, argc, argv, kw_splat);
}

Implementation of the Fiber.schedule. The method is expected to immediately run the given block of code in a separate non-blocking fiber, and to return that Fiber.

Minimal suggested implementation is:

def fiber(&block)
  fiber = Fiber.new(blocking: false, &block)
  fiber.resume
  fiber
end

fiber_interrupt(fiber, exception)

Source

VALUE rb_fiber_scheduler_fiber_interrupt(VALUE scheduler, VALUE fiber, VALUE exception)
{
    VALUE arguments[] = {
        fiber, exception
    };

    VALUE result;
    enum ruby_tag_type state;

    // We must prevent interrupts while invoking the fiber_interrupt method, because otherwise fibers can be left permanently blocked if an interrupt occurs during the execution of user code. See also `rb_fiber_scheduler_unblock`.
    rb_execution_context_t * volatile ec = GET_EC();
    volatile int saved_interrupt_mask = ec->interrupt_mask;
    ec->interrupt_mask |= PENDING_INTERRUPT_MASK;

    rb_control_frame_t *volatile cfp = ec->cfp;
    EC_PUSH_TAG(ec);
    if ((state = EC_EXEC_TAG()) == TAG_NONE) {
        result = rb_funcallv(scheduler, id_fiber_interrupt, 2, arguments);
    }
    else {
        rb_vm_rewind_cfp(ec, cfp);
    }
    EC_POP_TAG();

    ec->interrupt_mask = saved_interrupt_mask;

    if (state) {
        EC_JUMP_TAG(ec, state);
    }

    RUBY_VM_CHECK_INTS(ec);

    return result;
}

Invoked by Ruby’s core methods to notify the scheduler that the blocked fiber should be interrupted with an exception. For example, IO#close uses this method to interrupt fibers that are performing blocking IO operations.

io_close(fd)

Source

VALUE
rb_fiber_scheduler_io_close(VALUE scheduler, VALUE io)
{
    VALUE arguments[] = {io};

    return rb_check_funcall(scheduler, id_io_close, 1, arguments);
}

Invoked by Ruby’s core methods to notify scheduler that the IO object is closed. Note that the method will receive an integer file descriptor of the closed object, not an object itself.

io_pread(io, buffer, from, offset, length) → read length or -errno

Source

VALUE
rb_fiber_scheduler_io_pread(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t offset, size_t length)
{
    if (!rb_respond_to(scheduler, id_io_pread)) {
        return RUBY_Qundef;
    }

    VALUE arguments[] = {
        scheduler, io, buffer, OFFT2NUM(from), SIZET2NUM(offset), SIZET2NUM(length)
    };

    return rb_thread_io_blocking_operation(io, fiber_scheduler_io_pread, (VALUE)&arguments);
}

Invoked by IO#pread or IO::Buffer#pread to perform one read of at most length bytes from io at offset from into a specified buffer (see IO::Buffer), starting at the given offset.

This method is semantically the same as io_read, but it allows to specify the offset to read from and is often better for asynchronous IO on the same file.

io_pwrite(io, buffer, from, offset, length) → written length or -errno

Source

VALUE
rb_fiber_scheduler_io_pwrite(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t offset, size_t length)
{


    if (!rb_respond_to(scheduler, id_io_pwrite)) {
        return RUBY_Qundef;
    }

    VALUE arguments[] = {
        scheduler, io, buffer, OFFT2NUM(from), SIZET2NUM(offset), SIZET2NUM(length)
    };

    return rb_thread_io_blocking_operation(io, fiber_scheduler_io_pwrite, (VALUE)&arguments);
}

Invoked by IO#pwrite or IO::Buffer#pwrite to perform one write of at most length bytes to io at offset from from a specified buffer (see IO::Buffer), starting at the given offset.

This method is semantically the same as io_write, but it allows to specify the offset to write to and is often better for asynchronous IO on the same file.

io_read(io, buffer, offset, length) → read length or -errno

Source

VALUE
rb_fiber_scheduler_io_read(VALUE scheduler, VALUE io, VALUE buffer, size_t offset, size_t length)
{
    if (!rb_respond_to(scheduler, id_io_read)) {
        return RUBY_Qundef;
    }

    VALUE arguments[] = {
        scheduler, io, buffer, SIZET2NUM(offset), SIZET2NUM(length)
    };

    return rb_thread_io_blocking_operation(io, fiber_scheduler_io_read, (VALUE)&arguments);
}

Invoked by IO#read or IO::Buffer#read to perform one read of at most length bytes from io into a specified buffer (see IO::Buffer), starting at the given offset.

A short read is returned directly. Specifying a length of 0 returns 0 without performing a read.

The implementation should perform one non-blocking read and return -EAGAIN if io is not ready. The caller can then wait and retry as appropriate.

See IO::Buffer for an interface available to return data.

Expected to return number of bytes read, or, in case of an error, -errno (negated number corresponding to system’s error code).

io_select(readables, writables, exceptables, timeout)

Source

VALUE rb_fiber_scheduler_io_select(VALUE scheduler, VALUE readables, VALUE writables, VALUE exceptables, VALUE timeout)
{
    VALUE arguments[] = {
        readables, writables, exceptables, timeout
    };

    return rb_fiber_scheduler_io_selectv(scheduler, 4, arguments);
}

Invoked by IO.select to ask whether the specified descriptors are ready for specified events within the specified timeout.

Expected to return the 3-tuple of Array of IOs that are ready.

io_wait(io, events, timeout)

Source

VALUE
rb_fiber_scheduler_io_wait(VALUE scheduler, VALUE io, VALUE events, VALUE timeout)
{
    VALUE arguments[] = {
        scheduler, io, events, timeout
    };

    return rb_thread_io_blocking_operation(io, fiber_scheduler_io_wait, (VALUE)&arguments);
}

Invoked by IO#wait, IO#wait_readable, IO#wait_writable to ask whether the specified descriptor is ready for specified events within the specified timeout.

events is a bit mask of IO::READABLE, IO::WRITABLE, and IO::PRIORITY.

Suggested implementation should register which Fiber is waiting for which resources and immediately calling Fiber.yield to pass control to other fibers. Then, in the close method, the scheduler might dispatch all the I/O resources to fibers waiting for it.

Expected to return the subset of events that are ready immediately.

io_write(io, buffer, offset, length) → written length or -errno

Source

VALUE
rb_fiber_scheduler_io_write(VALUE scheduler, VALUE io, VALUE buffer, size_t offset, size_t length)
{
    if (!rb_respond_to(scheduler, id_io_write)) {
        return RUBY_Qundef;
    }

    VALUE arguments[] = {
        scheduler, io, buffer, SIZET2NUM(offset), SIZET2NUM(length)
    };

    return rb_thread_io_blocking_operation(io, fiber_scheduler_io_write, (VALUE)&arguments);
}

Invoked by IO#write or IO::Buffer#write to perform one write of at most length bytes to io from a specified buffer (see IO::Buffer), starting at the given offset.

A short write is returned directly. Specifying a length of 0 returns 0 without performing a write.

The implementation should perform one non-blocking write and return -EAGAIN if io is not ready. The caller can then wait and retry as appropriate.

See IO::Buffer for an interface available to get data from buffer efficiently.

Expected to return number of bytes written, or, in case of an error, -errno (negated number corresponding to system’s error code).

kernel_sleep(duration = nil)

Source

VALUE
rb_fiber_scheduler_kernel_sleep(VALUE scheduler, VALUE timeout)
{
    return rb_funcall(scheduler, id_kernel_sleep, 1, timeout);
}

Invoked by Kernel#sleep and Thread::Mutex#sleep and is expected to provide an implementation of sleeping in a non-blocking way. Implementation might register the current fiber in some list of “which fiber wait until what moment”, call Fiber.yield to pass control, and then in close resume the fibers whose wait period has elapsed.

process_wait(pid, flags)

Source

VALUE
rb_fiber_scheduler_process_wait(VALUE scheduler, rb_pid_t pid, int flags)
{
    VALUE arguments[] = {
        PIDT2NUM(pid), RB_INT2NUM(flags)
    };

    return rb_check_funcall(scheduler, id_process_wait, 2, arguments);
}

Invoked by Process::Status.wait in order to wait for a specified process. See that method description for arguments description.

Suggested minimal implementation:

Thread.new do
  Process::Status.wait(pid, flags)
end.value

This hook is optional: if it is not present in the current scheduler, Process::Status.wait will behave as a blocking method.

Expected to return a Process::Status instance.

timeout_after(duration, exception_class, *exception_arguments, &block) → result of block

Source

VALUE
rb_fiber_scheduler_timeout_after(VALUE scheduler, VALUE timeout, VALUE exception, VALUE message)
{
    VALUE arguments[] = {
        timeout, exception, message
    };

    return rb_check_funcall(scheduler, id_timeout_after, 3, arguments);
}

Invoked by Timeout.timeout to execute the given block within the given duration. It can also be invoked directly by the scheduler or user code.

Attempt to limit the execution time of a given block to the given duration if possible. When a non-blocking operation causes the block‘s execution time to exceed the specified duration, that non-blocking operation should be interrupted by raising the specified exception_class constructed with the given exception_arguments.

General execution timeouts are often considered risky. This implementation will only interrupt non-blocking operations. This is by design because it’s expected that non-blocking operations can fail for a variety of unpredictable reasons, so applications should already be robust in handling these conditions and by implication timeouts.

However, as a result of this design, if the block does not invoke any non-blocking operations, it will be impossible to interrupt it. If you desire to provide predictable points for timeouts, consider adding sleep(0).

If the block is executed successfully, its result will be returned.

The exception will typically be raised using Fiber#raise.

unblock(blocker, fiber)

Source

VALUE
rb_fiber_scheduler_unblock(VALUE scheduler, VALUE blocker, VALUE fiber)
{
    RUBY_ASSERT(rb_obj_is_fiber(fiber));

    VALUE result;
    enum ruby_tag_type state;

    // `rb_fiber_scheduler_unblock` can be called from points where `errno` is expected to be preserved. Therefore, we should save and restore it. For example `io_binwrite` calls `rb_fiber_scheduler_unblock` and if `errno` is reset to 0 by user code, it will break the error handling in `io_write`.
    //
    // If we explicitly preserve `errno` in `io_binwrite` and other similar functions (e.g. by returning it), this code is no longer needed. I hope in the future we will be able to remove it.
    int saved_errno = errno;

    // We must prevent interrupts while invoking the unblock method, because otherwise fibers can be left permanently blocked if an interrupt occurs during the execution of user code. See also `rb_fiber_scheduler_fiber_interrupt`.
    rb_execution_context_t * volatile ec = GET_EC();
    volatile int saved_interrupt_mask = ec->interrupt_mask;
    ec->interrupt_mask |= PENDING_INTERRUPT_MASK;

    rb_control_frame_t *volatile cfp = ec->cfp;
    EC_PUSH_TAG(ec);
    if ((state = EC_EXEC_TAG()) == TAG_NONE) {
        result = rb_funcall(scheduler, id_unblock, 2, blocker, fiber);
    }
    else {
        rb_vm_rewind_cfp(ec, cfp);
    }
    EC_POP_TAG();

    ec->interrupt_mask = saved_interrupt_mask;

    if (state) {
        EC_JUMP_TAG(ec, state);
    }

    RUBY_VM_CHECK_INTS(ec);

    errno = saved_errno;

    return result;
}

Invoked to wake up Fiber previously blocked with block (for example, Thread::Mutex#lock calls block and Thread::Mutex#unlock calls unblock). The scheduler should use the fiber parameter to understand which fiber is unblocked.

blocker is what was awaited for, but it is informational only (for debugging and logging), and it is not guaranteed to be the same value as the blocker for block.

yield

Source

VALUE
rb_fiber_scheduler_yield(VALUE scheduler)
{
    // First try to call the scheduler's yield method, if it exists:
    VALUE result = rb_check_funcall(scheduler, id_yield, 0, NULL);
    if (!UNDEF_P(result)) return result;

    // Otherwise, we can emulate yield by sleeping for 0 seconds:
    return rb_fiber_scheduler_kernel_sleep(scheduler, RB_INT2NUM(0));
}

Yield to the scheduler, to be resumed on the next scheduling cycle.