akr	2013-09-22 12:43:14 +0900 (Sun, 22 Sep 2013)

  New Revision: 43009

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=43009

  Log:
    [DOC]

  Modified files:
    trunk/io.c
Index: io.c
===================================================================
--- io.c	(revision 43008)
+++ io.c	(revision 43009)
@@ -8493,7 +8493,7 @@ rb_io_advise(int argc, VALUE *argv, VALU https://github.com/ruby/ruby/blob/trunk/io.c#L8493
  *  It is not happen for IO-like objects such as OpenSSL::SSL::SSLSocket.
  *
  *  The best way to use <code>IO.select</code> is invoking it
- *  after nonblocking methods such as <code>read_nonblock</code>.
+ *  after nonblocking methods such as <code>read_nonblock</code>, <code>write_nonblock</code>, etc.
  *  The methods raises an exception which is extended by
  *  <code>IO::WaitReadable</code> or <code>IO::WaitWritable</code>.
  *  The modules notify how the caller should wait with <code>IO.select</code>.
@@ -8555,6 +8555,26 @@ rb_io_advise(int argc, VALUE *argv, VALU https://github.com/ruby/ruby/blob/trunk/io.c#L8555
  *  Invoking <code>IO.select</code> before <code>IO#readpartial</code> works well in usual.
  *  However it is not the best way to use <code>IO.select</code>.
  *
+ *  The writability notified by select(2) doesn't show
+ *  how many bytes writable.
+ *  <code>IO#write</code> method blocks until given whole string is written.
+ *  So, <code>IO#write(two or more bytes)</code> can block after writability is notified by <code>IO.select</code>.
+ *  <code>IO#write_nonblock</code> is required to avoid the blocking.
+ *
+ *  Blocking write (<code>write</code>) can be emulated using
+ *  <code>write_nonblock</code> and <code>IO.select</code> as follows:
+ *  IO::WaitReadable should also be rescued for SSL renegotiation in <code>OpenSSL::SSL::SSLSocket</code>.
+ *
+ *    begin
+ *      result = io_like.write_nonblock(string)
+ *    rescue IO::WaitReadable
+ *      IO.select([io_like])
+ *      retry
+ *    rescue IO::WaitWritable
+ *      IO.select(nil, [io_like])
+ *      retry
+ *    end
+ *
  *  === Parameters
  *  read_array:: an array of <code>IO</code> objects that wait until ready for read
  *  write_array:: an array of <code>IO</code> objects that wait until ready for write

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