https://git.ruby-lang.org/ruby.git/commit/?id=7fcad1fa03

From 7fcad1fa03c21b9a9916a12b816ec886a5b68920 Mon Sep 17 00:00:00 2001
From: Samuel Williams <samuel.williams@o...>
Date: Sat, 15 Oct 2022 21:43:45 +1300
Subject: Update `Fiber::Scheduler` documentation. (#6562)

---
 cont.c                         | 340 +----------------------------------------
 include/ruby/fiber/scheduler.h |  34 +++--
 io.c                           |   4 +-
 scheduler.c                    | 310 ++++++++++++++++++++++++++++++++++++-
 4 files changed, 331 insertions(+), 357 deletions(-)

diff --git a/cont.c b/cont.c
index 39f0fc8171..b6d26d716e 100644
--- a/cont.c
+++ b/cont.c
@@ -1991,7 +1991,7 @@ rb_fiber_s_schedule_kw(int argc, VALUE* argv, int kw_splat) https://github.com/ruby/ruby/blob/trunk/cont.c#L1991
     VALUE fiber = Qnil;
 
     if (scheduler != Qnil) {
-        fiber = rb_funcall_passing_block_kw(scheduler, rb_intern("fiber"), argc, argv, kw_splat);
+        fiber = rb_fiber_scheduler_fiber(scheduler, argc, argv, kw_splat);
     }
     else {
         rb_raise(rb_eRuntimeError, "No scheduler is available!");
@@ -3000,329 +3000,6 @@ rb_fiber_pool_initialize(int argc, VALUE* argv, VALUE self) https://github.com/ruby/ruby/blob/trunk/cont.c#L3000
  *     fiber.resume #=> FiberError: dead fiber called
  */
 
-/*
- *  Document-class: Fiber::SchedulerInterface
- *
- *  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 #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).
- *
- *  A typical implementation would probably rely for this closing loop on a gem like
- *  EventMachine[https://github.com/eventmachine/eventmachine] or
- *  Async[https://github.com/socketry/async].
- *
- *  This way concurrent execution will be achieved transparently for every
- *  individual Fiber's code.
- *
- *  Hook methods are:
- *
- *  * #io_wait, #io_read, and #io_write
- *  * #process_wait
- *  * #kernel_sleep
- *  * #timeout_after
- *  * #address_resolve
- *  * #block and #unblock
- *  * (the list is expanded as Ruby developers make more methods having non-blocking calls)
- *
- *  When not specified otherwise, the hook implementations are mandatory: if they are not
- *  implemented, the methods trying to call hook will fail. To provide backward compatibility,
- *  in the future hooks will be optional (if they are not implemented, due to the scheduler
- *  being created for the older Ruby version, the code which needs this hook will not fail,
- *  and will just behave in a blocking fashion).
- *
- *  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
- *  <tt>test/fiber/scheduler.rb</tt>
- *
- */
-
-#if 0 /* for RDoc */
-/*
- *
- *  Document-method: Fiber::SchedulerInterface#close
- *
- *  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.
- *
- */
-static VALUE
-rb_fiber_scheduler_interface_close(VALUE self)
-{
-}
-
-/*
- *  Document-method: SchedulerInterface#process_wait
- *  call-seq: process_wait(pid, flags)
- *
- *  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.
- */
-static VALUE
-rb_fiber_scheduler_interface_process_wait(VALUE self)
-{
-}
-
-/*
- *  Document-method: SchedulerInterface#io_wait
- *  call-seq: io_wait(io, events, timeout)
- *
- *  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 <tt>IO::READABLE</tt>, <tt>IO::WRITABLE</tt>, and
- *  <tt>IO::PRIORITY</tt>.
- *
- *  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.
- *
- */
-static VALUE
-rb_fiber_scheduler_interface_io_wait(VALUE self)
-{
-}
-
-/*
- *  Document-method: SchedulerInterface#io_read
- *  call-seq: io_read(io, buffer, length) -> read length or -errno
- *
- *  Invoked by IO#read to read +length+ bytes from +io+ into a specified
- *  +buffer+ (see IO::Buffer).
- *
- *  The +length+ argument is the "minimum length to be read".
- *  If the IO buffer size is 8KiB, but the +length+ is +1024+ (1KiB), up to
- *  8KiB might be read, but at least 1KiB will be.
- *  Generally, the only case where less data than +length+ will be read is if
- *  there is an error reading the data.
- *
- *  Specifying a +length+ of 0 is valid and means try reading at least once
- *  and return any available data.
- *
- *  Suggested implementation should try to read from +io+ in a non-blocking
- *  manner and call #io_wait if the +io+ is not ready (which will yield control
- *  to other fibers).
- *
- *  See IO::Buffer for an interface available to return data.
- *
- *  Expected to return number of bytes read, or, in case of an error, <tt>-errno</tt>
- *  (negated number corresponding to system's error code).
- *
- *  The method should be considered _experimental_.
- */
-static VALUE
-rb_fiber_scheduler_interface_io_read(VALUE self)
-{
-}
-
-/*
- *  Document-method: SchedulerInterface#io_write
- *  call-seq: io_write(io, buffer, length) -> written length or -errno
- *
- *  Invoked by IO#write to write +length+ bytes to +io+ from
- *  from a specified +buffer+ (see IO::Buffer).
- *
- *  The +length+ argument is the "(minimum) length to be written".
- *  If the IO buffer size is 8KiB, but the +length+ specified is 1024 (1KiB),
- *  at most 8KiB will be written, but at least 1KiB will be.
- *  Generally, the only case where less data than +length+ will be written is if
- *  there is an error writing the data.
- *
- *  Specifying a +length+ of 0 is valid and means try writing at least once,
- *  as much data as possible.
- *
- *  Suggested implementation should try to write to +io+ in a non-blocking
- *  manner and call #io_wait if the +io+ is not ready (which will yield control
- *  to other fibers).
- *
- *  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, <tt>-errno</tt>
- *  (negated number corresponding to system's error code).
- *
- *  The method should be considered _experimental_.
- */
-static VALUE
-rb_fiber_scheduler_interface_io_write(VALUE self)
-{
-}
-
-/*
- *  Document-method: SchedulerInterface#kernel_sleep
- *  call-seq: kernel_sleep(duration = nil)
- *
- *  Invoked by Kernel#sleep and 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.
- *
- */
-static VALUE
-rb_fiber_scheduler_interface_kernel_sleep(VALUE self)
-{
-}
-
-/*
- *  Document-method: SchedulerInterface#address_resolve
- *  call-seq: address_resolve(hostname) -> array_of_strings or nil
- *
- *  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:
- *
- *  - Addrinfo.getaddrinfo
- *  - Addrinfo.tcp
- *  - Addrinfo.udp
- *  - Addrinfo.ip
- *  - Addrinfo.new
- *  - Addrinfo.marshal_load
- *  - SOCKSSocket.new
- *  - TCPServer.new
- *  - TCPSocket.new
- *  - IPSocket.getaddress
- *  - TCPSocket.gethostbyname
- *  - UDPSocket#connect
- *  - UDPSocket#bind
- *  - UDPSocket#send
- *  - Socket.getaddrinfo
- *  - Socket.gethostbyname
- *  - Socket.pack_sockaddr_in
- *  - Socket.sockaddr_in
- *  - Socket.unpack_sockaddr_in
- */
-static VALUE
-rb_fiber_scheduler_interface_address_resolve(VALUE self)
-{
-}
-
-/*
- *  Document-method: SchedulerInterface#timeout_after
- *  call-seq: timeout_after(duration, exception_class, *exception_arguments, &block) -> result of block
- *
- *  Invoked by Timeout.timeout to execute the given +block+ within the given
- *  +duration+. I (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/