[Python-checkins] python/dist/src/Doc/lib libsocket.tex,1.64,1.65

[gvanrossum@users.sourceforge.net]

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

Modified Files:
	libsocket.tex 
Log Message:
Clarify the interaction between blocking and timeouts.  Explain that
fromfd() assumes a blocking non-timeout socket.


Index: libsocket.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libsocket.tex,v
retrieving revision 1.64
retrieving revision 1.65
diff -C2 -d -r1.64 -r1.65
*** libsocket.tex	6 Jun 2002 22:24:10 -0000	1.64
--- libsocket.tex	7 Jun 2002 03:39:21 -0000	1.65
***************
*** 285,289 ****
  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).
  Availability: \UNIX.
  \end{funcdesc}
--- 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 created in blocking mode without
! a timeout.
  Availability: \UNIX.
  \end{funcdesc}
***************
*** 516,524 ****
  
  \begin{methoddesc}[socket]{settimeout}{value}
! Set a timeout on blocking socket operations. Value can be any numeric
! value or \code{None}. 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}
--- 517,526 ----
  
  \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
! give, 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}
***************
*** 526,542 ****
  \begin{methoddesc}[socket]{gettimeout}{}
  Returns the timeout in floating seconds associated with socket
! operations.  A timeout of \code{None} indicates that timeouts on
! socket operations are disabled.
  \versionadded{2.3}
  \end{methoddesc}
  
! Some notes on the interaction between socket blocking and timeouts:
! socket blocking mode takes precedence over timeouts. If a socket is
! set to non-blocking mode, then timeouts are not used.
! The timeout value associated with the socket can still be set using
! \method{settimeout()} and its value retrieved using
! \method{gettimeout()}, but the timeout is never enforced (an exception
! will never be thrown).  Otherwise, if the socket is in blocking mode,
! setting the timeout will raise an exception as expected.
  
  \begin{methoddesc}[socket]{setsockopt}{level, optname, value}
--- 528,549 ----
  \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).
  
  \begin{methoddesc}[socket]{setsockopt}{level, optname, value}