Apache Geode Native C++ Reference  1.14.0
apache::geode::client::PoolFactory Class Reference

This interface provides for the configuration and creation of instances of Pool. More...

Public Member Functions

PoolFactoryaddLocator (const std::string &host, int port)
 Adds a locator, given its host and port, to this factory. More...
 
PoolFactoryaddServer (const std::string &host, int port)
 Adds a server, given its host and port, to this factory. More...
 
std::shared_ptr< Poolcreate (std::string name)
 Creates a new Pool for connecting a client to a set of Geode Cache Servers. More...
 
PoolFactoryreset ()
 Resets the configuration of this factory to its defaults. More...
 
PoolFactorysetFreeConnectionTimeout (std::chrono::milliseconds connectionTimeout)
 Sets the free connection timeout for this pool. More...
 
PoolFactorysetIdleTimeout (std::chrono::milliseconds)
 Sets the amount of time a connection can be idle before expiring the connection. More...
 
PoolFactorysetLoadConditioningInterval (std::chrono::milliseconds loadConditioningInterval)
 Sets the load conditioning interval for this pool. More...
 
PoolFactorysetMaxConnections (int maxConnections)
 Sets the max number of client to server connections that the pool will create. More...
 
PoolFactorysetMinConnections (int minConnections)
 Sets the minimum number of connections to keep available at all times. More...
 
PoolFactorysetMultiuserAuthentication (bool multiuserAuthentication)
 Sets whether Pool is in multi user secure mode. More...
 
PoolFactorysetPingInterval (std::chrono::milliseconds pingInterval)
 The frequency with which servers must be pinged to verify that they are still alive. More...
 
PoolFactorysetPRSingleHopEnabled (bool enabled)
 By default setPRSingleHopEnabled is true. More...
 
PoolFactorysetReadTimeout (std::chrono::milliseconds timeout)
 Sets the duration to wait for a response from a server before timing out the operation and trying another server (if any are available). More...
 
PoolFactorysetRetryAttempts (int retryAttempts)
 Set the number of times to retry a request after timeout/exception. More...
 
PoolFactorysetServerGroup (std::string group)
 Configures the group which contains all the servers that this pool connects to. More...
 
PoolFactorysetSniProxy (std::string hostname, uint16_t port)
 Set proxy info for SNI connection. More...
 
PoolFactorysetSocketBufferSize (int bufferSize)
 Sets the socket buffer size for each connection made in this pool. More...
 
PoolFactorysetStatisticInterval (std::chrono::milliseconds statisticInterval)
 The frequency with which the client statistics must be sent to the server. More...
 
PoolFactorysetSubscriptionAckInterval (std::chrono::milliseconds ackInterval)
 Sets the is the interval to wait before sending acknowledgements to the bridge server for events received from the server subscriptions. More...
 
PoolFactorysetSubscriptionEnabled (bool enabled)
 If set to true then the created pool will have server-to-client subscriptions enabled. More...
 
PoolFactorysetSubscriptionMessageTrackingTimeout (std::chrono::milliseconds messageTrackingTimeout)
 Sets the messageTrackingTimeout attribute which is the time-to-live period for subscription events the client has received from the server. More...
 
PoolFactorysetSubscriptionRedundancy (int redundancy)
 Sets the redundancy level for this pools server-to-client subscriptions. More...
 
PoolFactorysetThreadLocalConnections (bool threadLocalConnections)
 Sets the thread local connections policy for this pool. More...
 
PoolFactorysetUpdateLocatorListInterval (std::chrono::milliseconds updateLocatorListInterval)
 The frequency with which client updates the locator list. More...
 

Static Public Attributes

static const std::chrono::milliseconds DEFAULT_FREE_CONNECTION_TIMEOUT
 The default amount of time which we will wait for a free connection if max connections is set and all of the connections are in use. More...
 
static const std::chrono::milliseconds DEFAULT_IDLE_TIMEOUT
 The default amount of time to wait for a connection to become idle. More...
 
static const std::chrono::milliseconds DEFAULT_LOAD_CONDITIONING_INTERVAL
 The default interval in which the pool will check to see if a connection to a given server should be moved to a different server to improve the load balance. More...
 
static const int DEFAULT_MAX_CONNECTIONS = -1
 The default maximum number of connections to be created. More...
 
static const int DEFAULT_MIN_CONNECTIONS = 1
 The default number of connections to be created initially. More...
 
static constexpr bool DEFAULT_MULTIUSER_SECURE_MODE = false
 Whether client is in multi user secure mode. More...
 
static const std::chrono::milliseconds DEFAULT_PING_INTERVAL
 The default frequency, to ping servers. More...
 
static constexpr bool DEFAULT_PR_SINGLE_HOP_ENABLED = true
 The default value for whether to have single hop optimizations enabled. More...
 
static const std::chrono::milliseconds DEFAULT_READ_TIMEOUT
 The default amount of time to wait for a response from a server. More...
 
static const int DEFAULT_RETRY_ATTEMPTS = -1
 The default number of times to retry an operation after a timeout or exception. More...
 
static const std::string DEFAULT_SERVER_GROUP
 The default server group. More...
 
static const int DEFAULT_SOCKET_BUFFER_SIZE = 32768
 The default size in bytes of the socket buffer on each connection established. More...
 
static const std::chrono::milliseconds DEFAULT_STATISTIC_INTERVAL
 The default frequency that client statistics are sent to the server. More...
 
static const std::chrono::milliseconds DEFAULT_SUBSCRIPTION_ACK_INTERVAL
 The default amount of time to wait before sending an acknowledgement to the server about events received from the subscriptions. More...
 
static const bool DEFAULT_SUBSCRIPTION_ENABLED = false
 The default value for whether to establish a server to client subscription. More...
 
static const std::chrono::milliseconds DEFAULT_SUBSCRIPTION_MESSAGE_TRACKING_TIMEOUT
 The default amount of time that messages sent from a server to a client will be tracked. More...
 
static const int DEFAULT_SUBSCRIPTION_REDUNDANCY = 0
 The default redundancy for servers holding subscriptions established by this client. More...
 
static constexpr bool DEFAULT_THREAD_LOCAL_CONN = false
 Whether thread local connection is enabled. More...
 
static const std::chrono::milliseconds DEFAULT_UPDATE_LOCATOR_LIST_INTERVAL
 The default frequency to update the locator list. More...
 

Detailed Description

This interface provides for the configuration and creation of instances of Pool.

Every pool needs to have at least one locator or server added to it. Locators should be added unless direct connections to bridge servers are desired.

The setter methods are used to specify non-default values for the other pool properties.

Once it is configured create will produce an instance.

The factory can be restored to its default configuration by calling reset.

Instances of this interface can be created by calling Cache#getPoolFactory.

If a subscription is going to be made using a pool then subscriptions must be enabled on the pool. Subscriptions are made using these APIs:

Member Function Documentation

◆ addLocator()

PoolFactory& apache::geode::client::PoolFactory::addLocator ( const std::string &  host,
int  port 
)

Adds a locator, given its host and port, to this factory.

The locator must be a server locator and will be used to discover other running bridge servers and locators.

Parameters
hostis the host name or ip address that the locator is listening on.
portis the port that the locator is listening on.
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif the host is an unknown host according to java.net.InetAddress#getByName or if the port is outside the valid range of [1..65535] inclusive.
IllegalStateExceptionif the locator has already been {added} to this factory.

◆ addServer()

PoolFactory& apache::geode::client::PoolFactory::addServer ( const std::string &  host,
int  port 
)

Adds a server, given its host and port, to this factory.

The server must be a bridge server and this client will directly connect to the server without consulting a server locator.

Parameters
hostis the host name or ip address that the server is listening on.
portis the port that the server is listening on.
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif the host is an unknown host according to java.net.InetAddress#getByName or if the port is outside the valid range of [1..65535] inclusive.
IllegalStateExceptionif the server has already been {added} to this factory.

◆ create()

std::shared_ptr<Pool> apache::geode::client::PoolFactory::create ( std::string  name)

Creates a new Pool for connecting a client to a set of Geode Cache Servers.

using this factory's settings for attributes.

Parameters
nameis the name of the pool, used when connecting regions to it
Exceptions
IllegalStateExceptionif a pool with name already exists
IllegalStateExceptionif a locator or server has not been added.
Returns
the newly created pool.

◆ reset()

PoolFactory& apache::geode::client::PoolFactory::reset ( )

Resets the configuration of this factory to its defaults.

Returns
a reference to this

◆ setFreeConnectionTimeout()

PoolFactory& apache::geode::client::PoolFactory::setFreeConnectionTimeout ( std::chrono::milliseconds  connectionTimeout)

Sets the free connection timeout for this pool.

If the pool has a max connections setting, operations will block if all of the connections are in use. The free connection timeout specifies how long those operations will block waiting for a free connection before receiving an AllConnectionsInUseException. If max connections is not set this setting has no effect.

See also
setMaxConnections(int)
Parameters
connectionTimeoutis the connection timeout
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif connectionTimeout is less than or equal to std::chrono::milliseconds::zero().

◆ setIdleTimeout()

PoolFactory& apache::geode::client::PoolFactory::setIdleTimeout ( std::chrono::milliseconds  )

Sets the amount of time a connection can be idle before expiring the connection.

If the pool size is greater than the minimum specified by PoolFactory#setMinConnections(int), connections which have been idle for longer than the idleTimeout will be closed.

Parameters
idleTimeoutis the duration that an idle connection should live no less than before expiring, actual time may be longer depending on clock resolution. A duration std::chrono::milliseconds::zero() indicates that connections should never expire.
Returns
a reference to this

◆ setLoadConditioningInterval()

PoolFactory& apache::geode::client::PoolFactory::setLoadConditioningInterval ( std::chrono::milliseconds  loadConditioningInterval)

Sets the load conditioning interval for this pool.

This interval controls how frequently the pool will check to see if a connection to a given server should be moved to a different server to improve the load balance.

A value of std::chrono::milliseconds::zero() disables load conditioning.

Parameters
loadConditioningIntervalis the connection lifetime
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif connectionLifetime is less than std::chrono::milliseconds::zero().

◆ setMaxConnections()

PoolFactory& apache::geode::client::PoolFactory::setMaxConnections ( int  maxConnections)

Sets the max number of client to server connections that the pool will create.

If all of the connections are in use, an operation requiring a client to server connection will block until a connection is available.

See also
#setFreeConnectionTimeout(int)
Parameters
maxConnectionsis the maximum number of connections in the pool. -1 indicates that there is no maximum number of connections
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif maxConnections is less than minConnections.

◆ setMinConnections()

PoolFactory& apache::geode::client::PoolFactory::setMinConnections ( int  minConnections)

Sets the minimum number of connections to keep available at all times.

When the pool is created, it will create this many connections. If 0 then connections will not be made until an actual operation is done that requires client-to-server communication.

Parameters
minConnectionsis the initial number of connections this pool will create.
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif minConnections is less than 0.

◆ setMultiuserAuthentication()

PoolFactory& apache::geode::client::PoolFactory::setMultiuserAuthentication ( bool  multiuserAuthentication)

Sets whether Pool is in multi user secure mode.

If its in multiuser mode then app needs to get RegionService instance of Cache. Default value is false.

Returns
a reference to this

◆ setPingInterval()

PoolFactory& apache::geode::client::PoolFactory::setPingInterval ( std::chrono::milliseconds  pingInterval)

The frequency with which servers must be pinged to verify that they are still alive.

Each server will be sent a ping every pingInterval if there has not been any other communication with the server.

These pings are used by the server to monitor the health of the client. Make sure that the pingInterval is less than the maximum time between pings allowed by the bridge server.

Parameters
pingIntervalis the amount of time between pings.
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif pingInterval is less than 0.
See also
CacheServer::setMaximumTimeBetweenPings(int)

◆ setPRSingleHopEnabled()

PoolFactory& apache::geode::client::PoolFactory::setPRSingleHopEnabled ( bool  enabled)

By default setPRSingleHopEnabled is true.


The client is aware of the locations of partitions on servers hosting partitioned regions. Using this information, the client routes client cache operations directly to the server which is hosting the required partition for the cache operation. If setPRSingleHopEnabled is false the client can do an extra hop on servers to go to the required partition for that cache operation. The setPRSingleHopEnabled setting avoids extra hops only for the following cache operations:

  1. Region#put(Object, Object)
  2. Region#get(Object)
  3. Region#destroy(Object)
    If true, works best when PoolFactory#setMaxConnections(int) is set to -1.
    Parameters
    enabledis a boolean indicating whether PR Single Hop optimization should be enabled or not.
    Returns
    a reference to this

◆ setReadTimeout()

PoolFactory& apache::geode::client::PoolFactory::setReadTimeout ( std::chrono::milliseconds  timeout)

Sets the duration to wait for a response from a server before timing out the operation and trying another server (if any are available).

Parameters
timeoutduration to wait for a response from a server
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif timeout is less than or equal to std::chrono::milliseconds::zero().

◆ setRetryAttempts()

PoolFactory& apache::geode::client::PoolFactory::setRetryAttempts ( int  retryAttempts)

Set the number of times to retry a request after timeout/exception.

Parameters
retryAttemptsis the number of times to retry a request after timeout/exception. -1 indicates that a request should be tried against every available server before failing
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif idleTimout is less than 0.

◆ setServerGroup()

PoolFactory& apache::geode::client::PoolFactory::setServerGroup ( std::string  group)

Configures the group which contains all the servers that this pool connects to.

Parameters
groupis the server group that this pool will connect to. If the value is null or "" then the pool connects to all servers.
Returns
a reference to this

◆ setSniProxy()

PoolFactory& apache::geode::client::PoolFactory::setSniProxy ( std::string  hostname,
uint16_t  port 
)

Set proxy info for SNI connection.

Used for connecting via SNI proxy.

◆ setSocketBufferSize()

PoolFactory& apache::geode::client::PoolFactory::setSocketBufferSize ( int  bufferSize)

Sets the socket buffer size for each connection made in this pool.

Large messages can be received and sent faster when this buffer is larger. Larger buffers also optimize the rate at which servers can send events for client subscriptions.

Parameters
bufferSizeis the size of the socket buffers used for reading and writing on each connection in this pool.
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif bufferSize is less than or equal to 0.

◆ setStatisticInterval()

PoolFactory& apache::geode::client::PoolFactory::setStatisticInterval ( std::chrono::milliseconds  statisticInterval)

The frequency with which the client statistics must be sent to the server.

Doing this allows GFMon to monitor clients.

A value of std::chrono::milliseconds::zero() disables the sending of client statistics to the server.

Parameters
statisticIntervalis the amount of time between sends of client statistics to the server.
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif statisticInterval is less than std::chrono::milliseconds::zero().

◆ setSubscriptionAckInterval()

PoolFactory& apache::geode::client::PoolFactory::setSubscriptionAckInterval ( std::chrono::milliseconds  ackInterval)

Sets the is the interval to wait before sending acknowledgements to the bridge server for events received from the server subscriptions.

Parameters
ackIntervalis the duration to wait before sending event acknowledgements.
Exceptions
IllegalArgumentExceptionif ackInterval is less than or equal to 0.
Returns
a reference to this

◆ setSubscriptionEnabled()

PoolFactory& apache::geode::client::PoolFactory::setSubscriptionEnabled ( bool  enabled)

If set to true then the created pool will have server-to-client subscriptions enabled.

If set to false then all Subscription* attributes are ignored at the time of creation.

Returns
a reference to this

◆ setSubscriptionMessageTrackingTimeout()

PoolFactory& apache::geode::client::PoolFactory::setSubscriptionMessageTrackingTimeout ( std::chrono::milliseconds  messageTrackingTimeout)

Sets the messageTrackingTimeout attribute which is the time-to-live period for subscription events the client has received from the server.

It is used to minimize duplicate events. Entries that have not been modified for this amount of time are expired from the list.

Parameters
messageTrackingTimeoutis the duration to set the timeout to.
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif messageTrackingTimeout is less than or equal to 0.

◆ setSubscriptionRedundancy()

PoolFactory& apache::geode::client::PoolFactory::setSubscriptionRedundancy ( int  redundancy)

Sets the redundancy level for this pools server-to-client subscriptions.

If 0 then no redundant copies are kept on the servers. Otherwise an effort is made to maintain the requested number of copies of the server-to-client subscriptions. At most, one copy per server is made up to the requested level.

Parameters
redundancyis the number of redundant servers for this client's subscriptions.
Returns
a reference to this
Exceptions
IllegalArgumentExceptionif redundancyLevel is less than -1.

◆ setThreadLocalConnections()

PoolFactory& apache::geode::client::PoolFactory::setThreadLocalConnections ( bool  threadLocalConnections)

Sets the thread local connections policy for this pool.

If true then any time a thread goes to use a connection from this pool it will check a thread local cache and see if it already has a connection in it. If so it will use it. If not it will get one from this pool and cache it in the thread local. This gets rid of thread contention for the connections but increases the number of connections the servers see.

If false then connections are returned to the pool as soon as the operation being done with the connection completes. This allows connections to be shared among multiple threads keeping the number of connections down.

Parameters
threadLocalConnectionsif true then enable thread local connections.
Returns
a reference to this

◆ setUpdateLocatorListInterval()

PoolFactory& apache::geode::client::PoolFactory::setUpdateLocatorListInterval ( std::chrono::milliseconds  updateLocatorListInterval)

The frequency with which client updates the locator list.

To disable this set its value to std::chrono::milliseconds::zero().

Parameters
updateLocatorListIntervalis the amount of time between checking locator list at locator.
Returns
a reference to this

Field Documentation

◆ DEFAULT_FREE_CONNECTION_TIMEOUT

const std::chrono::milliseconds apache::geode::client::PoolFactory::DEFAULT_FREE_CONNECTION_TIMEOUT
static

The default amount of time which we will wait for a free connection if max connections is set and all of the connections are in use.

Current value: 10s.

◆ DEFAULT_IDLE_TIMEOUT

const std::chrono::milliseconds apache::geode::client::PoolFactory::DEFAULT_IDLE_TIMEOUT
static

The default amount of time to wait for a connection to become idle.

Current value: 5s.

◆ DEFAULT_LOAD_CONDITIONING_INTERVAL

const std::chrono::milliseconds apache::geode::client::PoolFactory::DEFAULT_LOAD_CONDITIONING_INTERVAL
static

The default interval in which the pool will check to see if a connection to a given server should be moved to a different server to improve the load balance.

Current value: 5min

◆ DEFAULT_MAX_CONNECTIONS

const int apache::geode::client::PoolFactory::DEFAULT_MAX_CONNECTIONS = -1
static

The default maximum number of connections to be created.

Current value: -1.

◆ DEFAULT_MIN_CONNECTIONS

const int apache::geode::client::PoolFactory::DEFAULT_MIN_CONNECTIONS = 1
static

The default number of connections to be created initially.

Current value: 1.

◆ DEFAULT_MULTIUSER_SECURE_MODE

constexpr bool apache::geode::client::PoolFactory::DEFAULT_MULTIUSER_SECURE_MODE = false
static

Whether client is in multi user secure mode.

Current value: "false".

◆ DEFAULT_PING_INTERVAL

const std::chrono::milliseconds apache::geode::client::PoolFactory::DEFAULT_PING_INTERVAL
static

The default frequency, to ping servers.

Current value: 10s.

◆ DEFAULT_PR_SINGLE_HOP_ENABLED

constexpr bool apache::geode::client::PoolFactory::DEFAULT_PR_SINGLE_HOP_ENABLED = true
static

The default value for whether to have single hop optimizations enabled.

Current value: true.

◆ DEFAULT_READ_TIMEOUT

const std::chrono::milliseconds apache::geode::client::PoolFactory::DEFAULT_READ_TIMEOUT
static

The default amount of time to wait for a response from a server.

Current value: 10s.

◆ DEFAULT_RETRY_ATTEMPTS

const int apache::geode::client::PoolFactory::DEFAULT_RETRY_ATTEMPTS = -1
static

The default number of times to retry an operation after a timeout or exception.

Current value: -1.

◆ DEFAULT_SERVER_GROUP

const std::string apache::geode::client::PoolFactory::DEFAULT_SERVER_GROUP
static

The default server group.

Current value: "".

◆ DEFAULT_SOCKET_BUFFER_SIZE

const int apache::geode::client::PoolFactory::DEFAULT_SOCKET_BUFFER_SIZE = 32768
static

The default size in bytes of the socket buffer on each connection established.

Current value: 32768.

◆ DEFAULT_STATISTIC_INTERVAL

const std::chrono::milliseconds apache::geode::client::PoolFactory::DEFAULT_STATISTIC_INTERVAL
static

The default frequency that client statistics are sent to the server.

Current value: std::chrono::milliseconds::zero() (disabled).

◆ DEFAULT_SUBSCRIPTION_ACK_INTERVAL

const std::chrono::milliseconds apache::geode::client::PoolFactory::DEFAULT_SUBSCRIPTION_ACK_INTERVAL
static

The default amount of time to wait before sending an acknowledgement to the server about events received from the subscriptions.

Current value: 100ms.

◆ DEFAULT_SUBSCRIPTION_ENABLED

const bool apache::geode::client::PoolFactory::DEFAULT_SUBSCRIPTION_ENABLED = false
static

The default value for whether to establish a server to client subscription.

Current value: false.

◆ DEFAULT_SUBSCRIPTION_MESSAGE_TRACKING_TIMEOUT

const std::chrono::milliseconds apache::geode::client::PoolFactory::DEFAULT_SUBSCRIPTION_MESSAGE_TRACKING_TIMEOUT
static

The default amount of time that messages sent from a server to a client will be tracked.

The tracking is done to minimize duplicate events.

Current value: 900s.

◆ DEFAULT_SUBSCRIPTION_REDUNDANCY

const int apache::geode::client::PoolFactory::DEFAULT_SUBSCRIPTION_REDUNDANCY = 0
static

The default redundancy for servers holding subscriptions established by this client.

Current value: 0.

◆ DEFAULT_THREAD_LOCAL_CONN

constexpr bool apache::geode::client::PoolFactory::DEFAULT_THREAD_LOCAL_CONN = false
static

Whether thread local connection is enabled.

Current value: "false".

◆ DEFAULT_UPDATE_LOCATOR_LIST_INTERVAL

const std::chrono::milliseconds apache::geode::client::PoolFactory::DEFAULT_UPDATE_LOCATOR_LIST_INTERVAL
static

The default frequency to update the locator list.

Current value: 5s.


Apache Geode C++ Cache API Documentation