How Client/Server Connections Work
The server pools in your Apache Geode client processes manage all client connection requests to the server tier. To make the best use of the pool functionality, you should understand how the pool manages the server connections.
- Pool connections. The pool connection is used to send individual operations to the server to update cached data, to satisfy a local cache miss, or to run an ad hoc query. Each pool connection goes to a host/port location where a server is listening. The server responds to the request on the same connection. Generally, client threads use a pool connection for an individual operation and then return the connection to the pool for reuse, but you can configure to have connections owned by threads. This figure shows pool connections for one client and one server. At any time, a pool may have from zero to many pool connections to any of the servers.
Subscription connections. The subscription connection is used to stream cache events from the server to the client. To use this, set the client attribute
subscription-enabledto true. The server establishes a queue to asynchronously send subscription events and the pool establishes a subscription connection to handle the incoming messages. The events sent depend on how the client subscribes.
The pool gets server connection information from the server locators or, alternately, from the static server list.
- Server Locators. Server locators maintain information about which servers are available and which has the least load. New connections are sent to the least loaded servers. The pool requests server information from a locator when it needs a new connection. The pool randomly chooses the locator to use and the pool sticks with a locator until the connection fails.
- Static Server List. If you use a static server list, the pool shuffles it once at startup, to provide randomness between clients with the same list configuration, and then runs through the list round robin connecting as needed to the next server in the list. There is no load balancing or dynamic server discovery with the static server list.
When a pool needs a new connection, it goes through these steps until either it successfully establishes a connection, it has exhausted all available servers, or the
free-connection-timeout is reached.
- Requests server connection information from the locator or retrieves the next server from the static server list.
- Sends a connection request to the server.
If the pool fails to connect while creating a subscription connection or provisioning the pool to reach the
min-connections setting, it logs a fine level message and retries after the time indicated by
If an application thread calls an operation that needs a connection and the pool can’t create it, the operation returns a
Pool instance in your client maintains its own connection pool. The pool responds as efficiently as possible to connection loss and requests for new connections, opening new connections as needed. When you use a pool with the server locator, the pool can quickly respond to changes in server availability, adding new servers and disconnecting from unhealthy or dead servers with little or no impact on your client threads. Static server lists require more close attention as the client pool is only able to connect to servers at the locations specified in the list.
The pool adds a new pool connection when one of the following happens:
- The number of open connections is less than the
- A thread needs a connection, all open connections are in use, and adding another connection would not take the open connection count over the pool’s
max-connectionssetting. If the max-connections setting has been reached, the thread blocks until a connection becomes available.
The pool closes a pool connection when one of the following occurs:
- The client receives a connectivity exception from the server.
- The server doesn’t respond to a direct request or ping within the client’s configured
read-timeoutperiod. In this case, the pool removes all connections to that server.
- The number of pool connections exceeds the pool’s
min-connectionssetting and the client doesn’t send any requests over the connection for the
When it closes a connection that a thread is using, the pool switches the thread to another server connection, opening a new one if needed.
The pool’s subscription connection is established in the same way as the pool connections, by requesting server information from the locator and then sending a request to the server, or, if you are using a static server list, by connecting to the next server in the list.
The server sends ping messages once per second by a task scheduled in a timer.
You can adjust the interval with the system property
gemfire.serverToClientPingPeriod, specified in milliseconds.
The server sends its ping-interval setting to the client. The client then uses this and a
multiplier to establish a read-timeout in the cache.
You can set the client property
subscription-timeout-multiplier to enable timeout of the
subscription feed with failover to another server.
Value options include:
A value of zero (the default) disables timeouts.
A value of one or more times out the server connection after the specified number of ping intervals have elapsed. A value of one is not recommended.
When locators are used, the pool periodically conditions its pool connections. Each connection has an internal lifetime counter. When the counter reaches the configured
load-conditioning-interval, the pool checks with the locator to see if the connection is using the least loaded server. If not, the pool establishes a new connection to the least loaded server, silently puts it in place of the old connection, and closes the old connection. In either case, when the operation completes, the counter starts at zero. Conditioning happens behind the scenes and does not affect your application’s connection use. This automatic conditioning allows very efficient upscaling of your server pool. It is also useful following planned and unplanned server outages, during which time the entire client load will have been placed on a subset of the normal set of servers.