Document Fiber::SchedulerInterface#io_read and #io_write

1 files changed, 67 insertions, 1 deletions

diff --git a/cont.c b/cont.c
index 290be43012..f2d7788c56 100644
--- a/cont.c
+++ b/cont.c
@@ -2919,7 +2919,7 @@ rb_fiber_pool_initialize(int argc, VALUE* argv, VALUE self)
  *
  *  Hook methods are:
  *
- *  * #io_wait
+ *  * #io_wait, #io_read, and #io_write
  *  * #process_wait
  *  * #kernel_sleep
  *  * #block and #unblock
@@ -3003,6 +3003,70 @@ 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)
  *
@@ -3131,6 +3195,8 @@ Init_Cont(void)
     rb_define_method(rb_cFiberScheduler, "close", rb_fiber_scheduler_interface_close, 0);
     rb_define_method(rb_cFiberScheduler, "process_wait", rb_fiber_scheduler_interface_process_wait, 0);
     rb_define_method(rb_cFiberScheduler, "io_wait", rb_fiber_scheduler_interface_io_wait, 0);
+    rb_define_method(rb_cFiberScheduler, "io_read", rb_fiber_scheduler_interface_io_read, 0);
+    rb_define_method(rb_cFiberScheduler, "io_write", rb_fiber_scheduler_interface_io_write, 0);
     rb_define_method(rb_cFiberScheduler, "kernel_sleep", rb_fiber_scheduler_interface_kernel_sleep, 0);
     rb_define_method(rb_cFiberScheduler, "block", rb_fiber_scheduler_interface_block, 0);
     rb_define_method(rb_cFiberScheduler, "unblock", rb_fiber_scheduler_interface_unblock, 0);