类 Fiber::Scheduler

这不是一个现有的类，而是 Scheduler 对象应遵守的接口文档，以便用作 Fiber.scheduler 的参数并处理非阻塞 fiber。有关某些概念的说明，另请参见 Fiber 类文档中的“非阻塞 fiber”部分。

Scheduler 的行为和用法预期如下

通过这种方式，将为每个单独的 Fiber 代码透明地实现并发执行。

Scheduler 实现由 gem 提供，例如 Async。

钩子方法是

除非另有说明，否则钩子实现是强制性的：如果未实现，则尝试调用钩子的方法将失败。为了提供向后兼容性，将来钩子将是可选的（如果未实现，由于 scheduler 是为较旧的 Ruby 版本创建的，则需要此钩子的代码不会失败，并且只会以阻塞方式运行）。

还强烈建议 scheduler 实现 fiber 方法，该方法由 Fiber.schedule 委托。

调度程序的示例玩具实现可以在 Ruby 代码中找到，位于 test/fiber/scheduler.rb

公共实例方法

address_resolve(hostname) → array_of_strings or nil 单击以切换源

由执行非反向 DNS 查找的任何方法调用。最著名的方法是 Addrinfo.getaddrinfo，但还有许多其他方法。

该方法应返回一个字符串数组，对应于 hostname 解析到的 IP 地址，如果无法解析，则返回 nil。

所有可能的调用站点的相当详尽的列表

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

    return rb_check_funcall(scheduler, id_address_resolve, 1, arguments);
}
block(blocker, timeout = nil) 单击以切换源

由 Thread.join 等方法和 Mutex 调用，以表示当前 Fiber 被阻止，直至另行通知（例如 unblock）或直至 timeout 已过。

blocker 是我们正在等待的内容，仅供参考（用于调试和记录）。无法保证其值。

预期返回布尔值，指定阻塞操作是否成功。

VALUE
rb_fiber_scheduler_block(VALUE scheduler, VALUE blocker, VALUE timeout)
{
    return rb_funcall(scheduler, id_block, 2, blocker, timeout);
}
close() 单击以切换源

在当前线程退出时调用。调度程序应实现此方法，以允许所有等待的 fiber 完成其执行。

建议的模式是在 close 方法中实现主事件循环。

VALUE
rb_fiber_scheduler_close(VALUE scheduler)
{
    VM_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;
}
fiber(&block)

Fiber.schedule 的实现。该方法预期立即在单独的非阻塞 fiber 中运行给定的代码块，并返回该 Fiber。

建议的最小实现是

def fiber(&block)
  fiber = Fiber.new(blocking: false, &block)
  fiber.resume
  fiber
end
io_pread(io, buffer, from, length, offset) → read length or -errno 单击以切换源

由 IO#pread 或 IO::Buffer#pread 调用，以从偏移量 from 处读取 length 字节的 io 到指定 buffer（请参阅 IO::Buffer）中的给定 offset。

此方法在语义上与 io_read 相同，但它允许指定要从中读取的偏移量，并且通常更适合同一文件上的异步 IO。

该方法应被视为实验性的。

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

    return rb_check_funcall(scheduler, id_io_pread, 5, arguments);
}
io_pwrite(io, buffer, from, length, offset) → 写入长度或 -errno 点击以切换源

由 IO#pwrite 或 IO::Buffer#pwrite 调用，以在给定的 offset 处将 length 字节写入到 buffer（请参阅 IO::Buffer）中的偏移量 from 处的 io。

此方法在语义上与 io_write 相同，但它允许指定写入的偏移量，并且通常更适合同一文件上的异步 IO。

该方法应被视为实验性的。

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

    return rb_check_funcall(scheduler, id_io_pwrite, 5, arguments);
}
io_read(io, buffer, length, offset) → 读取长度或 -errno 点击以切换源

由 IO#read 或 IO#Buffer.read 调用，以从 io 中读取 length 字节到给定 offset 处的指定 buffer（请参阅 IO::Buffer）。

length 参数是“要读取的最小长度”。如果 IO 缓冲区大小为 8KiB，但 length 为 1024（1KiB），则最多可能读取 8KiB，但至少会读取 1KiB。通常，读取的数据少于 length 的唯一情况是读取数据时出错。

指定 length 为 0 是有效的，这意味着至少尝试读取一次并返回任何可用数据。

建议的实现应尝试以非阻塞方式从 io 中读取，如果 io 未准备就绪（这会将控制权让渡给其他协程），则调用 io_wait。

请参阅 IO::Buffer 以了解可用于返回数据的接口。

预期返回读取的字节数，或者在出错的情况下返回 -errno（对应于系统错误代码的负数）。

该方法应被视为实验性的。

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

    return rb_check_funcall(scheduler, id_io_read, 4, arguments);
}
io_select(readables, writables, exceptables, timeout) 点击以切换源

由 IO.select 调用，以询问指定的描述符是否在指定的 timeout 内准备好进行指定的事件。

预期返回准备就绪的 IO 的 Array 的 3 元组。

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);
}
io_wait(io, events, timeout) 点击切换源代码

由 IO#wait、IO#wait_readable、IO#wait_writable 调用，以询问指定的文件描述符是否在指定的 timeout 内为指定事件做好准备。

events 是 IO::READABLE、IO::WRITABLE 和 IO::PRIORITY 的位掩码。

建议的实现应注册哪个 Fiber 正在等待哪些资源，并立即调用 Fiber.yield 以将控制权传递给其他 fiber。然后，在 close 方法中，调度程序可能会将所有 I/O 资源分派给正在等待它的 fiber。

预期返回立即准备好的事件子集。

VALUE
rb_fiber_scheduler_io_wait(VALUE scheduler, VALUE io, VALUE events, VALUE timeout)
{
    return rb_funcall(scheduler, id_io_wait, 3, io, events, timeout);
}
io_write(io, buffer, length, offset) → 已写入长度或 -errno 点击切换源代码

由 IO#write 或 IO::Buffer#write 调用，以从指定 buffer（参见 IO::Buffer）的给定 offset 处向 io 写入 length 字节。

length 参数是“要写入的最小长度”。如果 IO 缓冲区大小为 8KiB，但指定的 length 为 1024 (1KiB)，则最多将写入 8KiB，但至少将写入 1KiB。通常，写入的数据少于 length 的唯一情况是写入数据时出错。

指定长度为 0 是有效的，表示至少尝试写入一次，尽可能多的数据。

建议的实现应尝试以非阻塞方式写入 io，并在 io 未准备就绪时调用 io_wait（这会将控制权让渡给其他 fiber）。

请参阅 IO::Buffer 以获取可用于从缓冲区高效获取数据的接口。

预期返回已写入的字节数，或者在出错的情况下返回 -errno（与系统错误代码相对应的负数）。

该方法应被视为实验性的。

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

    return rb_check_funcall(scheduler, id_io_write, 4, arguments);
}
kernel_sleep(duration = nil) 点击切换源代码

由 Kernel#sleep 和 Mutex#sleep 调用，并预期以非阻塞方式提供睡眠实现。实现可能会在“哪个 fiber 等待到什么时刻”的某个列表中注册当前 fiber，调用 Fiber.yield 以传递控制权，然后在 close 中恢复等待期已过的 fiber。

VALUE
rb_fiber_scheduler_kernel_sleep(VALUE scheduler, VALUE timeout)
{
    return rb_funcall(scheduler, id_kernel_sleep, 1, timeout);
}
process_wait(pid, flags) 点击切换源代码

由 Process::Status.wait 调用，以等待指定的进程。有关参数说明，请参阅该方法说明。

建议的最小实现

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

此挂钩是可选的：如果当前调度程序中不存在此挂钩，则 Process::Status.wait 将表现为阻塞方法。

预期返回 Process::Status 实例。

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);
}
timeout_after(duration, exception_class, *exception_arguments, &block) → result of block 单击以切换源

由 Timeout.timeout 调用，以在给定的 duration 内执行给定的 block。它也可以由调度程序或用户代码直接调用。

尝试将给定 block 的执行时间限制在给定的 duration 内（如果可能）。当非阻塞操作导致 block 的执行时间超过指定的 duration 时，应通过引发使用给定的 exception_arguments 构造的指定 exception_class 来中断该非阻塞操作。

通常认为一般执行超时是有风险的。此实现只会中断非阻塞操作。这是设计使然，因为预期非阻塞操作可能会由于各种不可预测的原因而失败，因此应用程序应该已经能够处理这些条件，并且隐含地能够处理超时。

但是，由于此设计，如果 block 不调用任何非阻塞操作，则无法中断它。如果您希望提供可预测的超时点，请考虑添加 +sleep(0)+。

如果成功执行 block，则将返回其结果。

异常通常将使用 Fiber#raise 触发。

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);
}
unblock(blocker, fiber) 单击以切换源

调用以唤醒先前使用 block 阻塞的 Fiber（例如，Mutex#lock 调用 block，Mutex#unlock 调用 unblock）。调度程序应使用 fiber 参数来了解哪个 fiber 已解除阻塞。

blocker 是等待的内容，但它仅供参考（用于调试和日志记录），并且不能保证与 block 的 blocker 相同。

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

    return rb_funcall(scheduler, id_unblock, 2, blocker, fiber);
}