* lib/net/protocol.rb (module Net): Added ReadTimeout to match

OpenTimeout.  ReadTimeout is now raised by rbuf_fill instead of
  Timeout::Error to help users distinguish what type of timeout
  occurred.  [ruby-trunk - Feature #6088]
* lib/net/pop.rb (module Net):  Updated documentation for ReadTimeout
  and OpenTimeout.
* lib/net/http.rb (module Net):  ditto
* lib/net/smtp.rb (module Net):  ditto
* lib/net/telnet.rb (module Net):  Net::ReadTimeout is now raised in
  waitfor to match Net::Protocol.
* test/net/http/test_http.rb:  Updated Timeout::Error expectation to
  Net::ReadTimeout.
* test/net/ftp/test_ftp.rb:  ditto


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

ChangeLog

@@ -1,3 +1,19 @@
+Thu Apr 12 06:15:44 2012  Eric Hodel  <drbrain@segment7.net>
+
+	* lib/net/protocol.rb (module Net):  Added ReadTimeout to match
+	  OpenTimeout.  ReadTimeout is now raised by rbuf_fill instead of
+	  Timeout::Error to help users distinguish what type of timeout
+	  occurred.  [ruby-trunk - Feature #6088]
+	* lib/net/pop.rb (module Net):  Updated documentation for ReadTimeout
+	  and OpenTimeout.
+	* lib/net/http.rb (module Net):  ditto
+	* lib/net/smtp.rb (module Net):  ditto
+	* lib/net/telnet.rb (module Net):  Net::ReadTimeout is now raised in
+	  waitfor to match Net::Protocol.
+	* test/net/http/test_http.rb:  Updated Timeout::Error expectation to
+	  Net::ReadTimeout.
+	* test/net/ftp/test_ftp.rb:  ditto
+
 Thu Apr 12 05:27:01 2012  Eric Hodel  <drbrain@segment7.net>
 
 	* lib/webrick/server.rb (module WEBrick::GenericServer):  A server

lib/net/http.rb

@@ -624,13 +624,13 @@ module Net   #:nodoc:
     # Number of seconds to wait for the connection to open. Any number
     # may be used, including Floats for fractional seconds. If the HTTP
     # object cannot open a connection in this many seconds, it raises a
-    # TimeoutError exception.
+    # Net::OpenTimeout exception.
     attr_accessor :open_timeout
 
     # Number of seconds to wait for one block to be read (via one read(2)
     # call). Any number may be used, including Floats for fractional
     # seconds. If the HTTP object cannot read data in this many seconds,
-    # it raises a TimeoutError exception.
+    # it raises a Net::ReadTimeout exception.
     attr_reader :read_timeout
 
     # Setter for the read_timeout attribute.

lib/net/pop.rb

@@ -498,12 +498,12 @@ module Net
 
     # Seconds to wait until a connection is opened.
     # If the POP3 object cannot open a connection within this time,
-    # it raises a TimeoutError exception.
+    # it raises a Net::OpenTimeout exception.
     attr_accessor :open_timeout
 
     # Seconds to wait until reading one block (by one read(1) call).
     # If the POP3 object cannot complete a read() within this time,
-    # it raises a TimeoutError exception.
+    # it raises a Net::ReadTimeout exception.
     attr_reader :read_timeout
 
     # Set the read timeout.

lib/net/protocol.rb

@@ -44,8 +44,19 @@ module Net # :nodoc:
   class ProtoCommandError      < ProtocolError; end
   class ProtoRetriableError    < ProtocolError; end
   ProtocRetryError = ProtoRetriableError
+
+  ##
+  # OpenTimeout, a subclass of Timeout::Error, is raised if a connection cannot
+  # be created within the open_timeout.
+
   class OpenTimeout            < Timeout::Error; end
 
+  ##
+  # ReadTimeout, a subclass of Timeout::Error, is raised if a chunk of the
+  # response cannot be read within the read_timeout.
+
+  class ReadTimeout            < Timeout::Error; end
+
 
   class BufferedIO   #:nodoc: internal use only
     def initialize(io)
@@ -144,7 +155,7 @@ module Net # :nodoc:
         if IO.select([@io], nil, nil, @read_timeout)
           retry
         else
-          raise Timeout::Error
+          raise Net::ReadTimeout
         end
       rescue IO::WaitWritable
         # OpenSSL::Buffering#read_nonblock may fail with IO::WaitWritable.
@@ -152,7 +163,7 @@ module Net # :nodoc:
         if IO.select(nil, [@io], nil, @read_timeout)
           retry
         else
-          raise Timeout::Error
+          raise Net::ReadTimeout
         end
       end
     end

lib/net/smtp.rb

@@ -364,12 +364,12 @@ module Net
 
     # Seconds to wait while attempting to open a connection.
     # If the connection cannot be opened within this time, a
-    # TimeoutError is raised.
+    # Net::OpenTimeout is raised.
     attr_accessor :open_timeout
 
     # Seconds to wait while reading one block (by one read(2) call).
     # If the read(2) call does not complete within this time, a
-    # TimeoutError is raised.
+    # Net::ReadTimeout is raised.
     attr_reader :read_timeout
 
     # Set the number of seconds to wait until timing-out a read(2)
@@ -448,8 +448,9 @@ module Net
     # * Net::SMTPSyntaxError
     # * Net::SMTPFatalError
     # * Net::SMTPUnknownError
+    # * Net::OpenTimeout
+    # * Net::ReadTimeout
     # * IOError
-    # * TimeoutError
     #
     def SMTP.start(address, port = nil, helo = 'localhost',
                    user = nil, secret = nil, authtype = nil,
@@ -509,8 +510,9 @@ module Net
     # * Net::SMTPSyntaxError
     # * Net::SMTPFatalError
     # * Net::SMTPUnknownError
+    # * Net::OpenTimeout
+    # * Net::ReadTimeout
     # * IOError
-    # * TimeoutError
     #
     def start(helo = 'localhost',
               user = nil, secret = nil, authtype = nil)   # :yield: smtp
@@ -653,8 +655,8 @@ module Net
     # * Net::SMTPSyntaxError
     # * Net::SMTPFatalError
     # * Net::SMTPUnknownError
+    # * Net::ReadTimeout
     # * IOError
-    # * TimeoutError
     #
     def send_message(msgstr, from_addr, *to_addrs)
       raise IOError, 'closed session' unless @socket
@@ -706,8 +708,8 @@ module Net
     # * Net::SMTPSyntaxError
     # * Net::SMTPFatalError
     # * Net::SMTPUnknownError
+    # * Net::ReadTimeout
     # * IOError
-    # * TimeoutError
     #
     def open_message_stream(from_addr, *to_addrs, &block)   # :yield: stream
       raise IOError, 'closed session' unless @socket

lib/net/telnet.rb

@@ -243,15 +243,15 @@ module Net
     #
     # Timeout:: the number of seconds to wait before timing out both the
     #           initial attempt to connect to host (in this constructor),
-    #           and all attempts to read data from the host (in #waitfor(),
+    #           which raises a Net::OpenTimeout, and all attempts to read data
-    #           #cmd(), and #login()).  Exceeding this timeout causes a
+    #           from the host, which raises a Net::ReadTimeout (in #waitfor(),
-    #           TimeoutError to be raised.  The default value is 10 seconds.
+    #           #cmd(), and #login()).  The default value is 10 seconds.
     #           You can disable the timeout by setting this value to false.
     #           In this case, the connect attempt will eventually timeout
     #           on the underlying connect(2) socket call with an
     #           Errno::ETIMEDOUT error (but generally only after a few
     #           minutes), but other attempts to read data from the host
-    #           will hand indefinitely if no data is forthcoming.
+    #           will hang indefinitely if no data is forthcoming.
     #
     # Waittime:: the amount of time to wait after seeing what looks like a
     #            prompt (that is, received data that matches the Prompt
@@ -554,7 +554,7 @@ module Net
       rest = ''
       until(prompt === line and not IO::select([@sock], nil, nil, waittime))
         unless IO::select([@sock], nil, nil, time_out)
-          raise TimeoutError, "timed out while waiting for more data"
+          raise Net::ReadTimeout, "timed out while waiting for more data"
         end
         begin
           c = @sock.readpartial(1024 * 1024)

test/net/ftp/test_ftp.rb

@@ -190,7 +190,7 @@ class FTPTest < Test::Unit::TestCase
         ftp = Net::FTP.new
         ftp.read_timeout = 0.2
         ftp.connect(SERVER_ADDR, server.port)
-        assert_raise(Timeout::Error) do
+        assert_raise(Net::ReadTimeout) do
           ftp.login
         end
         assert_match(/\AUSER /, commands.shift)
@@ -283,7 +283,7 @@ class FTPTest < Test::Unit::TestCase
         assert_match(/\AUSER /, commands.shift)
         assert_match(/\APASS /, commands.shift)
         assert_equal("TYPE I\r\n", commands.shift)
-        assert_raise(Timeout::Error) do
+        assert_raise(Net::ReadTimeout) do
           ftp.list
         end
         assert_equal("TYPE A\r\n", commands.shift)
@@ -393,7 +393,7 @@ class FTPTest < Test::Unit::TestCase
         assert_match(/\APASS /, commands.shift)
         assert_equal("TYPE I\r\n", commands.shift)
         buf = ""
-        assert_raise(Timeout::Error) do
+        assert_raise(Net::ReadTimeout) do
           ftp.retrbinary("RETR foo", 1024) do |s|
             buf << s
           end

test/net/http/test_http.rb

@@ -204,7 +204,7 @@ module TestNetHTTP_version_1_1_methods
       conn.open_timeout = 0.01
 
       th = Thread.new do
-        assert_raise(Timeout::Error) {
+        assert_raise(Net::ReadTimeout) {
           conn.get('/')
         }
       end