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

From dcc42d46882ebfea294eddb2b89d85606840e576 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?=
 <shyouhei@r...>
Date: Thu, 21 Apr 2022 14:54:00 +0900
Subject: [Doc] correct my understanding about nonblocking mode

I was wrong.  Nonblocking mode nowadays does not interface with
IO#read.  Document updated. [ci skip]
---
 include/ruby/io.h | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/include/ruby/io.h b/include/ruby/io.h
index 36857db8f8..13af824ed8 100644
--- a/include/ruby/io.h
+++ b/include/ruby/io.h
@@ -652,10 +652,23 @@ VALUE rb_io_get_write_io(VALUE io); https://github.com/ruby/ruby/blob/trunk/include/ruby/io.h#L652
 VALUE rb_io_set_write_io(VALUE io, VALUE w);
 
 /**
- * Sets an IO to a "nonblock mode".  This amends the way an IO operates so that
- * instead of waiting for rooms for  read/write, it returns errors.  In case of
- * multiplexed IO  situations it can be  vital for IO operations  not to block.
- * This is the key API to achieve that property.
+ * Instructs the OS to put its internal file structure into "nonblocking mode".
+ * This is  an in-Kernel concept.   Reading from/writing  to that file  using C
+ * function calls would return  -1 with errno set.  However when  it comes to a
+ * ruby program,  we hide that error  behind our `IO#read` method.   Ruby level
+ * `IO#read` blocks  regardless of this flag.   If you want to  avoid blocking,
+ * you should consider using methods like `IO#readpartial`.
+ *
+ * ```ruby
+ * require 'io/nonblock'
+ * STDIN.nonblock = true
+ * STDIN.gets # blocks.
+ * ```
+ *
+ * As of  writing there is  a room  of this API  in Fiber schedulers.   A Fiber
+ * scheduler could be written in a  way its behaviour depends on this property.
+ * You  need an  in-depth  understanding  of how  schedulers  work to  properly
+ * leverage this, though.
  *
  * @note  Note   however  that   nonblocking-ness  propagates   across  process
  *        boundaries.  You must  really carefully watch your  step when turning
-- 
cgit v1.2.1


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