Adds a new config MaxIdleConnectionPoolSize

Author: Zhen

src/main/asciidoc/client-applications.adoc

@@ -367,18 +367,21 @@ include::{python-examples}/config_trust_example.py[tags=config-trust]
 === Connection pool management
 
 The driver maintains a pool of connections. The pooled connections are reused by sessions and transaction to avoid overhead added by establishing new connections every time to run a query.
-The connections in the pool are created on demand. The connection pool always start with no pooled connection. New connections are created on demand by sessions and/or transactions. When sessions and/or transactions finished using connections, healthy ones are returned to the pool. These pooled connections are then reused by new sessions and transactions to execute queries.
+The connections in the pool are created on demand. The connection pool always start with no pooled connection. New connections are created on demand by sessions and/or transactions. When sessions and/or transactions finished using connections, healthy ones are returned to the pool. These pooled idle connections are then reused by new sessions and transactions to execute queries.
 
-Three connection pool related configuration settings are exposed via driver configuration, namely `maxConnectionLifetime`, `maxConnectionPoolSize` and `connectionAcquisitionTimeout`.
-Application users could tune these settings to fit the driver into application adoption based on appliation's performace requirement and resourse consumption limit on remote servers. 
+The driver exposes a few connection pool related configuration settings, which client builders could adjust when adopting the driver based on client performace requirement and resourse consumption limit of remote servers. 
 
 The detailed description of the available connection pool settings are listed bellow:
 
-* `maxConnectionLifetime` - Default value: Infinite. Pooled connections older than this threshold will be closed and removed from the pool. Such removal happens during connection acquisition so that new session is never backed by an old connection. Setting this option to a low value will cause a high connection churn and might result in a performance drop. It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its adopted application network infrastructure (such as router, load balancer, proxy, firewall, etc.). No maximum lifetime limit is imposed by default. Zero and negative values result in lifetime not being checked.
+* `MaxConnectionLifetime` - Default value: Infinite. Pooled connections older than this threshold will be closed and removed from the pool. Such removal happens during connection acquisition so that new session is never backed by an old connection. Setting this option to a low value will cause a high connection churn and might result in a performance drop. It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its adopted application network infrastructure (such as router, load balancer, proxy, firewall, etc.). No maximum lifetime limit is imposed by default. Zero and negative values result in lifetime not being checked.
+
+* `MaxConnectionPoolSize` - Default value: Infinite. It defines the maximum total number of connections allowed to be managed by the connection pool per host. The total pool size includes both the connections that are used by sessions and/or transactions and idle connections buffered by the pool. For direct driver, this sets the max amount of connections towards a single database. While for routing driver, this sets the max amount of connections towards each cluster member. When a session or transaction tries to acquire connection and pool is at its full capacity, then the session or transaction has to wait until a free connection is returned to the pool or the request to acquire a new connection times out (where an `ClientException` will be thrown). The connection acquiring timeout is configured via `connectionAcquisitionTimeout`.
+
+* `MaxIdleConnectionPoolSize` - This setting configures the maximum amount of idle connections buffered by the pool per host. When the pool has reached its max idle connection pool size, the connections that are ready to be returned to the pool will be closed directly rather than buffered by the pool. Configure this value higher for greater concurrency for spike demamds, or lower to reduce the pressure on remote server for maintaining unactive resources. For most usecases, we recommend setting this value to be the same as `MaxConnectionPoolSize` so that let the pool act as a fixed size connection pool. 
+
+* `ConnectionAcquisitionTimeout` - Default value: 1m. This setting limits amount of time a session or transaction can spend waiting for a free connection to appear in the pool before throwing an exception. Exception in this case is `ClientException`. Timeout only applies when connection pool is at its max capacity.
 
-* `maxConnectionPoolSize` - Default value: Infinite. It defines the maximum total number of connections allowed to be managed by the connection pool per host. In other words, for direct driver (with “bolt” uri scheme) this sets the max amount of connections towards a single database. While for routing driver (with “bolt+routing” uri scheme) this sets the max amount of connections towards each cluster member. When a session or transaction tries to acquire connection and pool is at its full capacity, then the session or transaction has to wait until a free connection is availble in the pool or the request to acquire a new connection times out. The connection acquiring timeout is configured via `connectionAcquisitionTimeout`.
 
-* `connectionAcquisitionTimeout` - Default value: 1m. This setting limits amount of time a session or transaction can spend waiting for a free connection to appear in the pool before throwing an exception. Exception in this case is `ClientException`. Timeout only applies when connection pool is at its max capacity.
 
 [.tabbed-example]
 .Connection pool management