Update docs for new pool options. PYTHON-436

Author: A. Jesse Jiryu Davis

doc/changelog.rst

@@ -18,6 +18,12 @@ Important new features:
 .. warning:: SIGNIFICANT BEHAVIOR CHANGE in 2.5.2+. Previously, `max_pool_size`
   would limit only the idle sockets the pool would hold onto, not the
   number of open sockets. The default has also changed, from 10 to 100.
+  If you pass a value for ``max_pool_size`` make sure it is large enough for
+  the expected load. (Sockets are only opened when needed, so there is no cost
+  to having a ``max_pool_size`` larger than necessary. Err towards a larger
+  value.) If your application accepts the default, continue to do so.
+
+  See :ref:`connection-pooling` for more information.
 
 Changes in Version 2.5.2
 ------------------------

doc/examples/requests.rst

@@ -94,3 +94,17 @@ the previous example more terse:
   2
   >>> client.in_request() # request automatically ended
   False
+
+Requests And ``max_pool_size``
+------------------------------
+
+A thread in a request retains exclusive access to a socket until its request
+ends or the thread dies; thus, applications in which more than 100 threads are
+in requests at once should disable the ``max_pool_size`` option::
+
+    client = MongoClient(host, port, max_pool_size=None)
+
+Failure to increase or disable ``max_pool_size`` in such an application can
+leave threads forever waiting for sockets.
+
+See :ref:`connection-pooling`

doc/faq.rst

@@ -17,14 +17,60 @@ How does connection pooling work in PyMongo?
 Every :class:`~pymongo.mongo_client.MongoClient` instance has a built-in
 connection pool. The pool begins with one open connection. If necessary to
 support concurrent access to MongoDB from multiple threads in your application,
-the client will open new connections on demand.
+the client opens new connections on demand.
 
 By default, there is no thread-affinity for connections.
 
-The size of the connection pool is capped at ``max_pool_size`` (default 100).
-When a thread in your application begins an operation on MongoDB, if no
-connections are available and the pool has reach its maximum, the thread
-blocks waiting for a connection to be returned to the pool by another thread.
+In versions before 2.6, the default ``max_pool_size`` was 10, and it did not
+actually bound the number of open connections; it only determined the number
+of connections that would be kept open when no longer in use.
+
+Starting with PyMongo 2.6, the size of the connection pool is capped at
+``max_pool_size``, which now defaults to 100. When a thread in your application
+begins an operation on MongoDB, if all other connections are in use and the
+pool has reached its maximum, the thread pauses, waiting for a connection to
+be returned to the pool by another thread.
+
+The default configuration for a :class:`~pymongo.mongo_client.MongoClient`
+works for most applications::
+
+    client = MongoClient(host, port)
+
+Create this client **once** when your program starts up, and reuse it for all
+operations. It is a common mistake to create a new client for each request,
+which is very inefficient.
+
+To support extremely high numbers of concurrent MongoDB operations within one
+process, increase ``max_pool_size``::
+
+    client = MongoClient(host, port, max_pool_size=200)
+
+... or make it unbounded::
+
+    client = MongoClient(host, port, max_pool_size=None)
+
+By default, any number of threads are allowed to wait for connections to become
+available, and they can wait any length of time. Override ``waitQueueMultiple``
+to cap the number of waiting threads. E.g., to keep the number of waiters less
+than or equal to 500::
+
+    client = MongoClient(host, port, max_pool_size=50, waitQueueMultiple=10)
+
+When 500 threads are waiting for a socket, the 501st that needs a connection
+raises :exc:`~pymongo.errors.ExceededMaxWaiters`. Use this option to
+bound the amount of queueing in your application during a load spike, at the
+cost of additional exceptions.
+
+Once the pool reaches its max size, additional threads are allowed to wait
+indefinitely for connections to become available, unless you set
+``waitQueueTimeoutMS``::
+
+    client = MongoClient(host, port, waitQueueTimeoutMS=100)
+
+A thread that waits more than 100ms (in this example) for a connection raises
+:exc:`~pymongo.errors.ConnectionFailure`. Use this option if it is more
+important to bound the duration of operations during a load spike than it is to
+complete every operation.
 
 When :meth:`~pymongo.mongo_client.MongoClient.disconnect` is called by any thread,
 all sockets are closed.

pymongo/connection.py

@@ -84,8 +84,10 @@ def __init__(self, host=None, port=None, max_pool_size=10,
             it must be enclosed in '[' and ']' characters following
             the RFC2732 URL syntax (e.g. '[::1]' for localhost)
           - `port` (optional): port number on which to connect
-          - `max_pool_size` (optional): The maximum size limit for
-            the connection pool.
+          - `max_pool_size` (optional): The maximum number of connections
+            that the pool will open simultaneously. If this is set, operations
+            will block if there are `max_pool_size` outstanding connections
+            from the pool. Defaults to 100.
           - `network_timeout` (optional): timeout (in seconds) to use
             for socket operations - default is no timeout
           - `document_class` (optional): default class to use for

pymongo/errors.py

@@ -109,3 +109,13 @@ class UnsupportedOption(ConfigurationError):
 
     .. versionadded:: 2.0
     """
+
+
+class ExceededMaxWaiters(Exception):
+    """Raised when a thread tries to get a connection from a pool and
+    ``max_pool_size * waitQueueMultiple`` threads are already waiting.
+
+    .. versionadded:: 2.6
+    """
+    pass
+

pymongo/mongo_replica_set_client.py

@@ -526,8 +526,10 @@ def __init__(self, hosts_or_uri=None, max_pool_size=100,
             pairs. If a host is an IPv6 literal it must be enclosed in '[' and
             ']' characters following the RFC2732 URL syntax (e.g. '[::1]' for
             localhost)
-          - `max_pool_size` (optional): The maximum number of idle connections
-            to keep open in each pool for future use
+          - `max_pool_size` (optional): The maximum number of connections
+            each pool will open simultaneously. If this is set, operations
+            will block if there are `max_pool_size` outstanding connections
+            from the pool. Defaults to 100.
           - `document_class` (optional): default class to use for
             documents returned from queries on this client
           - `tz_aware` (optional): if ``True``,

pymongo/replica_set_connection.py

@@ -80,8 +80,10 @@ def __init__(self, hosts_or_uri=None, max_pool_size=10,
             pairs. If a host is an IPv6 literal it must be enclosed in '[' and
             ']' characters following the RFC2732 URL syntax (e.g. '[::1]' for
             localhost)
-          - `max_pool_size` (optional): The maximum size limit for
-            each connection pool.
+          - `max_pool_size` (optional): The maximum number of connections
+            each pool will open simultaneously. If this is set, operations
+            will block if there are `max_pool_size` outstanding connections
+            from the pool. Defaults to 100.
           - `document_class` (optional): default class to use for
             documents returned from queries on this connection
           - `tz_aware` (optional): if ``True``,

pymongo/thread_util.py

@@ -35,6 +35,8 @@
 except ImportError:
     have_gevent = False
 
+from pymongo.errors import ExceededMaxWaiters
+
 
 # Do we have to work around http://bugs.python.org/issue1868?
 issue1868 = (sys.version_info[:3] <= (2, 7, 0))
@@ -244,10 +246,6 @@ def release(self):
         pass
 
 
-class ExceededMaxWaiters(Exception):
-    pass
-
-
 class MaxWaitersBoundedSemaphore(object):
     def __init__(self, semaphore_class, value=1, max_waiters=1):
         self.waiter_semaphore = semaphore_class(max_waiters)

test/test_pooling_base.py

@@ -31,7 +31,7 @@
 from pymongo.mongo_client import MongoClient
 from pymongo.pool import Pool, NO_REQUEST, NO_SOCKET_YET, SocketInfo
 from pymongo.errors import ConfigurationError, ConnectionFailure
-from pymongo.thread_util import ExceededMaxWaiters
+from pymongo.errors import ExceededMaxWaiters
 from test import version, host, port
 from test.test_client import get_client
 from test.utils import delay, is_mongos, one