update rdoc and NEWS.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@23010 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 31 insertions, 0 deletions

diff --git a/lib/openssl/buffering.rb b/lib/openssl/buffering.rb
index 10d7b9d..8e67fd7 100644
--- a/lib/openssl/buffering.rb
+++ b/lib/openssl/buffering.rb
@@ -100,6 +100,37 @@ module Buffering
     ret
   end
 
+  # Reads at most _maxlen_ bytes in the non-blocking manner.
+  #
+  # When no data can be read without blocking,
+  # It raises OpenSSL::SSL::SSLError extended by
+  # IO::WaitReadable or IO::WaitWritable.
+  #
+  # IO::WaitReadable means SSL needs to read internally.
+  # So read_nonblock should be called again after
+  # underlying IO is readable.
+  #
+  # IO::WaitWritable means SSL needs to write internally.
+  # So read_nonblock should be called again after
+  # underlying IO is writable.
+  #
+  # So OpenSSL::Buffering#read_nonblock needs two rescue clause as follows.
+  # 
+  #  begin
+  #    result = ssl.read_nonblock(maxlen)
+  #  rescue IO::WaitReadable
+  #    IO.select([io])
+  #    retry
+  #  rescue IO::WaitWritable
+  #    IO.select(nil, [io])
+  #    retry
+  #  end
+  #
+  # Note that one reason that read_nonblock write to a underlying IO
+  # is the peer requests a new TLS/SSL handshake.
+  # See openssl FAQ for more details.
+  # http://www.openssl.org/support/faq.html
+  #
   def read_nonblock(maxlen, buf=nil)
     if maxlen == 0
       if buf