Skip to content

Commit e52f596

Browse files
olim7tolim7t
committed
Improve pool documentation (JAVA-826).
1 parent 63a60a7 commit e52f596

2 files changed

Lines changed: 36 additions & 9 deletions

File tree

‎driver-core/src/main/java/com/datastax/driver/core/PoolingOptions.java‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,8 @@ public int getCoreConnectionsPerHost(HostDistance distance) {
185185
*
186186
* @throws IllegalArgumentException if {@code distance == HostDistance.IGNORED},
187187
* or if {@code newCoreConnections} is greater than the maximum value for this distance.
188+
*
189+
* @see #setConnectionsPerHost(HostDistance, int, int)
188190
*/
189191
public synchronized PoolingOptions setCoreConnectionsPerHost(HostDistance distance, int newCoreConnections) {
190192
if (distance == HostDistance.IGNORED)
@@ -220,6 +222,8 @@ public int getMaxConnectionsPerHost(HostDistance distance) {
220222
*
221223
* @throws IllegalArgumentException if {@code distance == HostDistance.IGNORED},
222224
* or if {@code newMaxConnections} is less than the core value for this distance.
225+
*
226+
* @see #setConnectionsPerHost(HostDistance, int, int)
223227
*/
224228
public synchronized PoolingOptions setMaxConnectionsPerHost(HostDistance distance, int newMaxConnections) {
225229
if (distance == HostDistance.IGNORED)

‎features/pooling/README.md‎

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -77,17 +77,39 @@ poolingOptions
7777
.setMaxConnectionsPerHost( HostDistance.REMOTE, 4);
7878
```
7979

80-
Note: the setters always enforce core <= max, which can get annoying
81-
when you try to set both values at once.
82-
[JAVA-662](https://datastax-oss.atlassian.net/browse/JAVA-662) will
83-
address this issue.
80+
For convenience, core and max can be set simultaneously:
8481

85-
[PoolingOptions.setMaxSimultaneousRequestsPerConnectionThreshold][msrpct]
86-
has a slightly misleading name: it does not limit the number of requests per
87-
connection, but only determines the threshold that triggers the creation
88-
of a new connection when the pool is not at its maximum capacity. In
89-
general, you shouldn't have to change its default value.
82+
```java
83+
poolingOptions
84+
.setConnectionsPerHost(HostDistance.LOCAL, 4, 10)
85+
.setConnectionsPerHost(HostDistance.REMOTE, 2, 4);
86+
```
87+
88+
The default settings are:
89+
90+
* `LOCAL` hosts: core = 2, max = 8
91+
* `REMOTE` hosts: core = 1, max = 2
92+
93+
#### Dynamic resizing
94+
95+
If core != max, the pool will resize automatically to adjust to the
96+
current activity on the host.
97+
98+
When activity goes up and there are *n* connections with n < max, the driver
99+
will add a connection when the number of concurrent requests is more than
100+
(n - 1) * 128 + [PoolingOptions.setMaxSimultaneousRequestsPerConnectionThreshold][msrpct]
101+
(in layman's terms, when all but the last connection are full and the last
102+
connection is above the threshold).
90103

104+
When activity goes down, the driver will "trash" connections if the maximum
105+
number of requests in a 10 second time period can be satisfied by less than
106+
the number of connections opened. Trashed connections are kept open but do
107+
not accept new requests. After a given timeout (defined by
108+
[PoolingOptions.setIdleTimeoutSeconds][sits]), trashed connections are closed
109+
and removed. If during that idle period activity increases again, those
110+
connections will be resurrected back into the active pool and reused. The
111+
main intent of that is to not constantly recreate connections if activity
112+
changes quickly over an interval.
91113

92114
#### Heartbeat
93115

@@ -180,6 +202,7 @@ could get away with less core connections.
180202
[pooling_options]:http://docs.datastax.com/en/drivers/java/2.0/com/datastax/driver/core/PoolingOptions.html
181203
[lbp]:http://docs.datastax.com/en/drivers/java/2.0/com/datastax/driver/core/policies/LoadBalancingPolicy.html
182204
[msrpct]:http://docs.datastax.com/en/drivers/java/2.0/com/datastax/driver/core/PoolingOptions.html#setMaxSimultaneousRequestsPerConnectionThreshold(com.datastax.driver.core.HostDistance,%20int)
205+
[sits]: http://docs.datastax.com/en/drivers/java/2.0/com/datastax/driver/core/PoolingOptions.html#setIdleTimeoutSeconds(int)
183206
[rtm]:http://docs.datastax.com/en/drivers/java/2.0/com/datastax/driver/core/SocketOptions.html#getReadTimeoutMillis()
184207
[exec_async]:http://docs.datastax.com/en/drivers/java/2.0/com/datastax/driver/core/Session.html#executeAsync(com.datastax.driver.core.Statement)
185208
[ptm]:http://docs.datastax.com/en/drivers/java/2.0/com/datastax/driver/core/PoolingOptions.html#setPoolTimeoutMillis(int)

0 commit comments

Comments
 (0)