[Python-checkins] python/dist/src/Doc/lib libsocket.tex,1.67,1.68

[gvanrossum@users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv22620/Doc/lib

Modified Files:
	libsocket.tex 
Log Message:
Major overhaul of timeout sockets:

- setblocking(0) and settimeout(0) are now equivalent, and ditto for
  setblocking(1) and settimeout(None).

- Don't raise an exception from internal_select(); let the final call
  report the error (this means you will get an EAGAIN error instead of
  an ETIMEDOUT error -- I don't care).

- Move the select to inside the Py_{BEGIN,END}_ALLOW_THREADS brackets,
  so other theads can run (this was a bug in the original code).

- Redid the retry logic in connect() and connect_ex() to avoid masking
  errors.  This probably doesn't work for Windows yet; I'll fix that
  next.  It may also fail on other platforms, depending on what
  retrying a connect does; I need help with this.

- Get rid of the retry logic in accept().  I don't think it was needed
  at all.  But I may be wrong.


Index: libsocket.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libsocket.tex,v
retrieving revision 1.67
retrieving revision 1.68
diff -C2 -d -r1.67 -r1.68
*** libsocket.tex	7 Jun 2002 12:38:23 -0000	1.67
--- libsocket.tex	13 Jun 2002 15:07:43 -0000	1.68
***************
*** 73,78 ****
  \exception{socket.error}.
  
! Non-blocking mode is supported through the
! \method{setblocking()} method.
  
  The module \module{socket} exports the following constants and functions:
--- 73,79 ----
  \exception{socket.error}.
  
! Non-blocking mode is supported through
! \method{setblocking()}.  A generalization of this based on timeouts
! is supported through \method{settimeout()}.
  
  The module \module{socket} exports the following constants and functions:
***************
*** 285,290 ****
  used to get or set socket options on a socket passed to a program as
  standard input or output (such as a server started by the \UNIX{} inet
! daemon).  The socket is assumed to be in blocking mode without
! a timeout.
  Availability: \UNIX.
  \end{funcdesc}
--- 286,290 ----
  used to get or set socket options on a socket passed to a program as
  standard input or output (such as a server started by the \UNIX{} inet
! daemon).  The socket is assumed to be in blocking mode.
  Availability: \UNIX.
  \end{funcdesc}
***************
*** 515,527 ****
  \exception{error} exception is raised; in blocking mode, the calls
  block until they can proceed.
  \end{methoddesc}
  
  \begin{methoddesc}[socket]{settimeout}{value}
! Set a timeout on blocking socket operations. Value can be a
! nonnegative float expressing seconds, or \code{None}.  If a float is
  given, subsequent socket operations will raise an \exception{error}
  exception if the timeout period \var{value} has elapsed before the
  operation has completed.  Setting a timeout of \code{None} disables
  timeouts on socket operations.
  \versionadded{2.3}
  \end{methoddesc}
--- 515,532 ----
  \exception{error} exception is raised; in blocking mode, the calls
  block until they can proceed.
+ \code{s.setblocking(0)} is equivalent to \code{s.settimeout(0)};
+ \code{s.setblocking(1)} is equivalent to \code{s.settimeout(None)}.
  \end{methoddesc}
  
  \begin{methoddesc}[socket]{settimeout}{value}
! Set a timeout on blocking socket operations.  The \var{value} argument
! can be a nonnegative float expressing seconds, or \code{None}.
! If a float is
  given, subsequent socket operations will raise an \exception{error}
  exception if the timeout period \var{value} has elapsed before the
  operation has completed.  Setting a timeout of \code{None} disables
  timeouts on socket operations.
+ \code{s.settimeout(0.0)} is equivalent to \code{s.blocking(0)};
+ \code{s.settimeout(None)} is equivalent to \code{s.setblocking(1)}.
  \versionadded{2.3}
  \end{methoddesc}
***************
*** 529,550 ****
  \begin{methoddesc}[socket]{gettimeout}{}
  Returns the timeout in floating seconds associated with socket
! operations, or \code{None} if no timeout is set.
  \versionadded{2.3}
  \end{methoddesc}
  
! Some notes on the interaction between socket blocking and timeouts: A
! socket object can be in one of three modes: blocking, non-blocking, or
! timout.  Sockets are always created in blocking mode.  In blocking
! mode, operations block until complete.  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.
! 
! Calling \method{settimeout()} cancels non-blocking mode as set by
! \method{setblocking()}; calling \method{setblocking()} cancels a
! previously set timeout.  Setting the timeout to zero acts similarly
! but is implemented different than setting the socket in non-blocking
! mode (this could be considered a bug and may even be fixed).
  
  Timeout mode internally sets the socket in non-blocking mode.  The
--- 534,551 ----
  \begin{methoddesc}[socket]{gettimeout}{}
  Returns the timeout in floating seconds associated with socket
! operations, or \code{None} if no timeout is set.  This reflects
! the last call to \method{setblocking()} or \method{settimeout()}.
  \versionadded{2.3}
  \end{methoddesc}
  
! Some notes on socket blocking and timeouts: A socket object can be in
! one of three modes: blocking, non-blocking, or timout.  Sockets are
! always created in blocking mode.  In blocking mode, operations block
! until complete.  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
! \method{setblocking()} method is simply a shorthand for certain
! \method{settimeout()} calls.
  
  Timeout mode internally sets the socket in non-blocking mode.  The