Document the way BaseServer closes the client socket. See #594. [skip ci]

changelog.rst

@@ -62,6 +62,16 @@ Unreleased
 - ``gevent.pool.Group.imap`` and ``imap_unordered`` now accept
   multiple iterables like ``itertools.imap``. Issue #565 reported by
   Thomas Steinacher.
+- Potentially breaking change: ``gevent.baseserver.BaseServer`` and
+  its subclass ``gevent.server.StreamServer`` now deterministically
+  close the client socket when the request handler returns.
+  Previously, the socket was left at the mercies of the garbage
+  collector; under CPython 2.x this meant when the last reference went
+  away, which was usually, but not necessarily, when the request
+  handler returned, but under PyPy it was some arbitrary point in the
+  future and under CPython 3.x a ResourceWarning could be generated.
+  This was undocumented behaviour, and the client socket could be kept
+  open after the request handler returned either accidentally or intentionally.
 
 Release 1.0.2
 =============

doc/reference.rst

@@ -7,6 +7,7 @@ API reference
    networking
    synchronization
    gevent.pool
+   gevent.threadpool
    servers
    gevent.local
    gevent.monkey

doc/servers.rst

@@ -51,8 +51,7 @@ More examples are available in the `code repository`_:
 
 .. toctree::
 
+   gevent.baseserver
    gevent.server
    gevent.pywsgi
    gevent.wsgi
-
-

gevent/baseserver.py

@@ -12,23 +12,39 @@ __all__ = ['BaseServer']
 
 
 class BaseServer(object):
-    """An abstract base class that implements some common functionality for the servers in gevent.
-
-    *listener* can either be an address that the server should bind on or a :class:`gevent.socket.socket`
-    instance that is already bound (and put into listening mode in case of TCP socket).
-
-    *spawn*, if provided, is called to create a new greenlet to run the handler. By default, :func:`gevent.spawn` is used.
+    """
+    An abstract base class that implements some common functionality for the servers in gevent.
+
+    :param listener: Either be an address that the server should bind
+        on or a :class:`gevent.socket.socket` instance that is already
+        bound (and put into listening mode in case of TCP socket).
+
+    :keyword handle: If given, the request handler. The request
+        handler can be defined in a few ways. Most commonly,
+        subclasses will implement a ``handle`` method as an
+        instance method. Alternatively, a function can be passed
+        as the ``handle`` argument to the constructor. In either
+        case, the handler can later be changed by calling
+        :meth:`set_handle`.
+
+        When the request handler returns, the socket used for the
+        request will be closed. (New in gevent 1.1a1.)
+
+    :keyword spawn: If provided, is called to create a new
+        greenlet to run the handler. By default,
+        :func:`gevent.spawn` is used (meaning there is no
+        artificial limit on the number of concurrent requests). Possible values for *spawn*:
+
+        - a :class:`gevent.pool.Pool` instance -- ``handle`` will be executed
+          using :meth:`gevent.pool.Pool.spawn` only if the pool is not full.
+          While it is full, all the connection are dropped;
+        - :func:`gevent.spawn_raw` -- ``handle`` will be executed in a raw
+          greenlet which have a little less overhead then :class:`gevent.Greenlet` instances spawned by default;
+        - ``None`` -- ``handle`` will be executed right away, in the :class:`Hub` greenlet.
+          ``handle`` cannot use any blocking functions as it means switching to the :class:`Hub`.
+        - an integer -- a shortcut for ``gevent.pool.Pool(integer)``
 
-    Possible values for *spawn*:
 
-    * a :class:`gevent.pool.Pool` instance -- *handle* will be executed
-      using :meth:`Pool.spawn` method only if the pool is not full.
-      While it is full, all the connection are dropped;
-    * :func:`gevent.spawn_raw` -- *handle* will be executed in a raw
-      greenlet which have a little less overhead then :class:`gevent.Greenlet` instances spawned by default;
-    * ``None`` -- *handle* will be executed right away, in the :class:`Hub` greenlet.
-      *handle* cannot use any blocking functions as it means switching to the :class:`Hub`.
-    * an integer -- a shortcut for ``gevent.pool.Pool(integer)``
     """
     # the number of seconds to sleep in case there was an error in accept() call
     # for consecutive errors the delay will double until it reaches max_delay

gevent/server.py

@@ -41,6 +41,8 @@ class StreamServer(BaseServer):
 
     The delay starts with :attr:`min_delay` and doubles with each successive error until it reaches :attr:`max_delay`.
     A successful :func:`accept` resets the delay to :attr:`min_delay` again.
+
+    See :class:`BaseServer` for information on defining the *handle* function and important restrictions on it.
     """
     # the default backlog to use if none was provided in __init__
     backlog = 256