From cae7c1d824fa77bb100356a7ed81f16b88e531c0 Mon Sep 17 00:00:00 2001
From: Antoine Pitrou <solipsis@pitrou.net>
Date: Sun, 2 Jan 2011 22:35:59 +0000
Subject: [PATCH] Merged revisions 87653-87655 via svnmerge from
 svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r87653 | antoine.pitrou | 2011-01-02 23:06:53 +0100 (dim., 02 janv. 2011) | 3 lines

  Clarify behaviour of close() and shutdown() on sockets.
........
  r87654 | antoine.pitrou | 2011-01-02 23:09:27 +0100 (dim., 02 janv. 2011) | 3 lines

  Add a shutdown() call in the server example.
........
  r87655 | antoine.pitrou | 2011-01-02 23:12:22 +0100 (dim., 02 janv. 2011) | 3 lines

  Some nits.
........
---
 Doc/library/socket.rst | 21 +++++++++++++++------
 Doc/library/ssl.rst    | 25 ++++++++++++++-----------
 2 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index bbe512b52da..48773012950 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -26,6 +26,15 @@ files, buffer allocation on receive operations is automatic, and buffer length
 is implicit on send operations.
 
 
+.. seealso::
+
+   Module :mod:`socketserver`
+      Classes that simplify writing network servers.
+
+   Module :mod:`ssl`
+      A TLS/SSL wrapper for socket objects.
+
+
 Socket families
 ---------------
 
@@ -487,12 +496,6 @@ The module :mod:`socket` exports the following constants and functions:
    same as ``type(socket(...))``.
 
 
-.. seealso::
-
-   Module :mod:`socketserver`
-      Classes that simplify writing network servers.
-
-
 .. _socket-objects:
 
 Socket Objects
@@ -522,6 +525,12 @@ correspond to Unix system calls applicable to sockets.
    remote end will receive no more data (after queued data is flushed). Sockets are
    automatically closed when they are garbage-collected.
 
+   .. note::
+      :meth:`close()` releases the resource associated with a connection but
+      does not necessarily close the connection immediately.  If you want
+      to close the connection in a timely fashion, call :meth:`shutdown()`
+      before :meth:`close()`.
+
 
 .. method:: socket.connect(address)
 
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index d3770722d66..2902318648e 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -1,8 +1,8 @@
-:mod:`ssl` --- SSL wrapper for socket objects
-=============================================
+:mod:`ssl` --- TLS/SSL wrapper for socket objects
+=================================================
 
 .. module:: ssl
-   :synopsis: SSL wrapper for socket objects
+   :synopsis: TLS/SSL wrapper for socket objects
 
 .. moduleauthor:: Bill Janssen <bill.janssen@gmail.com>
 .. sectionauthor::  Bill Janssen <bill.janssen@gmail.com>
@@ -537,13 +537,17 @@ the other end, and use :func:`wrap_socket` to create a server-side SSL context
 for it::
 
    while True:
-      newsocket, fromaddr = bindsocket.accept()
-      connstream = ssl.wrap_socket(newsocket,
-                                   server_side=True,
-                                   certfile="mycertfile",
-                                   keyfile="mykeyfile",
-                                   ssl_version=ssl.PROTOCOL_TLSv1)
-      deal_with_client(connstream)
+       newsocket, fromaddr = bindsocket.accept()
+       connstream = ssl.wrap_socket(newsocket,
+                                    server_side=True,
+                                    certfile="mycertfile",
+                                    keyfile="mykeyfile",
+                                    ssl_version=ssl.PROTOCOL_TLSv1)
+       try:
+           deal_with_client(connstream)
+       finally:
+           connstream.shutdown(socket.SHUT_RDWR)
+           connstream.close()
 
 Then you'd read data from the ``connstream`` and do something with it till you
 are finished with the client (or the client is finished with you)::
@@ -559,7 +563,6 @@ are finished with the client (or the client is finished with you)::
             break
          data = connstream.read()
       # finished with client
-      connstream.close()
 
 And go back to listening for new client connections.