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?= 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(-) (limited to 'include/ruby/io.h') 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); 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.3