[Python-checkins] r69731 - python/trunk/Doc/library/socket.rst

[gregory.p.smith]

Author: gregory.p.smith
Date: Wed Feb 18 06:46:11 2009
New Revision: 69731

Log:
Clarify socket timeout behavior vs system network stack behavior on connect
for issue5293.


Modified:
   python/trunk/Doc/library/socket.rst

Modified: python/trunk/Doc/library/socket.rst
==============================================================================
--- python/trunk/Doc/library/socket.rst	(original)
+++ python/trunk/Doc/library/socket.rst	Wed Feb 18 06:46:11 2009
@@ -726,12 +726,13 @@
 
 Some notes on socket blocking and timeouts: A socket object can be in one of
 three modes: blocking, non-blocking, or timeout.  Sockets are always created in
-blocking mode.  In blocking mode, operations block until complete.  In
+blocking mode.  In blocking mode, operations block until complete or
+the system returns an error (such as connection timed out).  In
 non-blocking mode, operations fail (with an error that is unfortunately
 system-dependent) if they cannot be completed immediately.  In timeout mode,
 operations fail if they cannot be completed within the timeout specified for the
-socket.  The :meth:`setblocking` method is simply a shorthand for certain
-:meth:`settimeout` calls.
+socket or if the system returns an error.  The :meth:`setblocking` method is simply
+a shorthand for certain :meth:`settimeout` calls.
 
 Timeout mode internally sets the socket in non-blocking mode.  The blocking and
 timeout modes are shared between file descriptors and socket objects that refer
@@ -742,7 +743,9 @@
 
 Note that the :meth:`connect` operation is subject to the timeout setting, and
 in general it is recommended to call :meth:`settimeout` before calling
-:meth:`connect`.
+:meth:`connect` or pass a timeout parameter to :meth:`create_connection`.
+The system network stack may return a connection timeout error
+of its own regardless of any python socket timeout setting.
 
 
 .. method:: socket.setsockopt(level, optname, value)