SERVER-27802 add comments to PoolForHost header

2 files changed, 20 insertions, 2 deletions

diff --git a/src/mongo/client/connpool.cpp b/src/mongo/client/connpool.cpp
index 5ef2b4e72e0..9ad9d62bb5e 100644
--- a/src/mongo/client/connpool.cpp
+++ b/src/mongo/client/connpool.cpp
@@ -216,6 +216,8 @@ DBClientBase* DBConnectionPool::_finishCreate(const string& ident,
 }
 
 DBClientBase* DBConnectionPool::get(const ConnectionString& url, double socketTimeout) {
+    // If a connection for this host is available from the underlying PoolForHost, use the
+    // connection in the pool.
     DBClientBase* c = _get(url.toString(), socketTimeout);
     if (c) {
         try {
@@ -227,6 +229,8 @@ DBClientBase* DBConnectionPool::get(const ConnectionString& url, double socketTi
         return c;
     }
 
+    // If no connections for this host are available in the PoolForHost (that is, all the
+    // connections have been checked out, or none have been created yet), create a new connection.
     string errmsg;
     c = url.connect(StringData(), errmsg, socketTimeout);
     uassert(13328, _name + ": connect failed " + url.toString() + " : " + errmsg, c);
diff --git a/src/mongo/client/connpool.h b/src/mongo/client/connpool.h
index 342bc0e2ae6..4599a6fdf30 100644
--- a/src/mongo/client/connpool.h
+++ b/src/mongo/client/connpool.h
@@ -48,8 +48,22 @@ struct ConnectionPoolStats;
 }  // namespace executor
 
 /**
- * not thread safe
- * thread safety is handled by DBConnectionPool
+ * The PoolForHost is responsible for storing a maximum of _maxPoolSize connections to a particular
+ * host. It is not responsible for creating new connections; instead, when DBConnectionPool is asked
+ * for a connection to a particular host, DBConnectionPool will check if any connections are
+ * available in the PoolForHost for that host. If so, DBConnectionPool will check out a connection
+ * from PoolForHost, and if not, DBConnectionPool will create a new connection itself.
+ *
+ * Once the connection is released back to DBConnectionPool, DBConnectionPool will attempt to
+ * release the connection to PoolForHost. This is how connections enter PoolForHost for the first
+ * time. If PoolForHost is below the _maxPoolSize limit, PoolForHost will take ownership of the
+ * connection, otherwise PoolForHost will clean up and destroy the connection.
+ *
+ * Additionally, PoolForHost knows how to purge itself of stale connections (since a connection can
+ * go stale while it is just sitting in the pool), but does not decide when to do so. Instead,
+ * DBConnectionPool tells PoolForHost to purge stale connections periodically.
+ *
+ * PoolForHost is not thread-safe; thread safety is handled by DBConnectionPool.
  */
 class PoolForHost {
     MONGO_DISALLOW_COPYING(PoolForHost);