Class PoolingOptions

Represents the options related to connection pooling.

For each host selected by the load balancing policy, the driver keeps a core amount of connections open at all times (GetCoreConnectionsPerHost(HostDistance)). If the use of those connections reaches a configurable threshold (GetMaxSimultaneousRequestsPerConnectionTreshold(HostDistance)), more connections are created up to the configurable maximum number of connections (GetMaxConnectionPerHost(HostDistance)).

The driver uses connections in an asynchronous manner and multiple requests can be submitted on the same connection at the same time without waiting for a response. This means that the driver only needs to maintain a relatively small number of connections to each Cassandra host. The PoolingOptions allows you to to control how many connections are kept per host.

Each of these parameters can be separately set for Local and Remote hosts. For Ignored hosts, the default for all those settings is 0 and cannot be changed.

The default amount of connections depend on the Cassandra version of the Cluster, as newer versions of Cassandra (2.1 and above) support a higher number of in-flight requests.

For Cassandra 2.1 and above, the default amount of connections per host are:

• Local datacenter: 1 core connection per host, with 2 connections as maximum when the simultaneous requests threshold is reached.
• Remote datacenter: 1 core connection per host (being 1 also max).

For older Cassandra versions (1.2 and 2.0), the default amount of connections per host are:

• Local datacenter: 2 core connection per host, with 8 connections as maximum when the simultaneous requests threshold is reached.
• Remote datacenter: 1 core connection per host (being 2 the maximum).

Inheritance

object

PoolingOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Cassandra

Assembly: Cassandra.dll

Syntax

public class PoolingOptions

Constructors

PoolingOptions()

DEPRECATED: It will be removed in future versions. Use Create(ProtocolVersion) instead.

Creates a new instance of PoolingOptions using defaults suitable for old server versions (Apache Cassandra 2.0 and below) for compatibility reasons. It's recommended that you use Create(ProtocolVersion) providing the server protocol version.

Declaration

public PoolingOptions()

Fields

DefaultHeartBeatInterval

The default heartbeat interval in milliseconds: 30000.

Declaration

public const int DefaultHeartBeatInterval = 30000

Field Value

Type	Description
int

DefaultMaxRequestsPerConnection

Default maximum amount of requests that can be in-flight on a single connection at the same time after which the connection will start rejecting requests: 2048.

Declaration

public const int DefaultMaxRequestsPerConnection = 2048

Field Value

Type	Description
int

Methods

Create(ProtocolVersion)

Creates a new instance of PoolingOptions using the default amount of connections and settings based on the protocol version.

For modern server versions (Apache Cassandra 2.1+) the amount of core connections are set to 1, setting 2 for max local connections.

Declaration

public static PoolingOptions Create(ProtocolVersion protocolVersion = ProtocolVersion.DseV2)

Parameters

Type	Name	Description
ProtocolVersion	protocolVersion

Returns

Type	Description
PoolingOptions	A new instance of PoolingOptions

See Also

ProtocolVersion

GetCoreConnectionsPerHost(HostDistance)

The core number of connections per host.

For the provided HostDistance, this correspond to the number of connections initially created and kept open to each host of that distance.

Declaration

public int GetCoreConnectionsPerHost(HostDistance distance)

Parameters

Type	Name	Description
HostDistance	distance	The HostDistance for which to return this threshold.

Returns

Type	Description
int	the core number of connections per host at distance HostDistance.

GetHeartBeatInterval()

Gets the amount of idle time in milliseconds that has to pass before the driver issues a request on an active connection to avoid idle time disconnections. A value of 0 or null means that the heartbeat functionality at connection level is disabled.

Declaration

public int? GetHeartBeatInterval()

Returns

Type	Description
int?

GetMaxConnectionPerHost(HostDistance)

The maximum number of connections per host.

For the provided distance, this correspond to the maximum number of connections that can be created per host at that distance.

Declaration

public int GetMaxConnectionPerHost(HostDistance distance)

Parameters

Type	Name	Description
HostDistance	distance	the HostDistance for which to return this threshold.

Returns

Type	Description
int	the maximum number of connections per host at distance distance.

GetMaxRequestsPerConnection()

Gets the maximum amount of requests that can be in-flight on a single connection at the same time.

This setting acts as a fixed maximum, once this value is reached for a host the pool will start rejecting requests, throwing BusyPoolException instances.

This setting should not be mistaken with GetMaxSimultaneousRequestsPerConnectionTreshold(HostDistance).

Declaration

public int GetMaxRequestsPerConnection()

Returns

Type	Description
int

GetMaxSimultaneousRequestsPerConnectionTreshold(HostDistance)

Number of simultaneous requests on each connections to a host after which more connections are created.

If all the connections opened to a host are handling more than this number of simultaneous requests and there is less than GetMaxConnectionPerHost(HostDistance) connections open to this host, a new connection is open.

Declaration

public int GetMaxSimultaneousRequestsPerConnectionTreshold(HostDistance distance)

Parameters

Type	Name	Description
HostDistance	distance	the HostDistance for which to return this threshold.

Returns

Type	Description
int	the configured threshold, or the default one if none have been set.

GetMinSimultaneousRequestsPerConnectionTreshold(HostDistance)

Number of simultaneous requests on a connection below which connections in excess are reclaimed.

If an opened connection to an host at distance distance handles less than this number of simultaneous requests and there is more than #GetCoreConnectionsPerHost connections open to this host, the connection is closed.

The default value for this option is 25 for Local and Remote hosts.

Declaration

public int GetMinSimultaneousRequestsPerConnectionTreshold(HostDistance distance)

Parameters

Type	Name	Description
HostDistance	distance	the HostDistance for which to return this threshold.

Returns

Type	Description
int	the configured threshold, or the default one if none have been set.

GetWarmup()

Gets whether all connections to hosts in the local datacenter must be opened on connect. Default: true.

Declaration

public bool GetWarmup()

Returns

Type	Description
bool

SetCoreConnectionsPerHost(HostDistance, int)

Sets the core number of connections per host.

Declaration

public PoolingOptions SetCoreConnectionsPerHost(HostDistance distance, int coreConnections)

Parameters

Type	Name	Description
HostDistance	distance	the HostDistance for which to set this threshold.
int	coreConnections	the value to set

Returns

Type	Description
PoolingOptions	this PoolingOptions.

SetHeartBeatInterval(int)

Sets the amount of idle time in milliseconds that has to pass before the driver issues a request on an active connection to avoid idle time disconnections. When set to 0 the heartbeat functionality at connection level is disabled.

Declaration

public PoolingOptions SetHeartBeatInterval(int value)

Parameters

Type	Name	Description
int	value

Returns

Type	Description
PoolingOptions

SetMaxConnectionsPerHost(HostDistance, int)

Sets the maximum number of connections per host.

Declaration

public PoolingOptions SetMaxConnectionsPerHost(HostDistance distance, int maxConnections)

Parameters

Type	Name	Description
HostDistance	distance	the HostDistance for which to set this threshold.
int	maxConnections	the value to set

Returns

Type	Description
PoolingOptions	this PoolingOptions.

SetMaxRequestsPerConnection(int)

Sets the maximum amount of requests that can be in-flight on a single connection at the same time.

This setting acts as a fixed maximum, once this value is reached for a host the pool will start rejecting requests, throwing BusyPoolException instances.

This setting should not be mistaken with SetMaxSimultaneousRequestsPerConnectionTreshold(HostDistance, int).

Declaration

public PoolingOptions SetMaxRequestsPerConnection(int value)

Parameters

Type	Name	Description
int	value

Returns

Type	Description
PoolingOptions

SetMaxSimultaneousRequestsPerConnectionTreshold(HostDistance, int)

Sets number of simultaneous requests on all connections to an host after which more connections are created.

Declaration

public PoolingOptions SetMaxSimultaneousRequestsPerConnectionTreshold(HostDistance distance, int maxSimultaneousRequests)

Parameters

Type	Name	Description
HostDistance	distance	The HostDistance for which to configure this threshold.
int	maxSimultaneousRequests	the value to set.

Returns

Type	Description
PoolingOptions	this PoolingOptions.

SetMinSimultaneousRequestsPerConnectionTreshold(HostDistance, int)

Sets the number of simultaneous requests on a connection below which connections in excess are reclaimed.

Declaration

public PoolingOptions SetMinSimultaneousRequestsPerConnectionTreshold(HostDistance distance, int minSimultaneousRequests)

Parameters

Type	Name	Description
HostDistance	distance	the HostDistance for which to configure this threshold.
int	minSimultaneousRequests	the value to set.

Returns

Type	Description
PoolingOptions	this PoolingOptions.

SetWarmup(bool)

Sets whether all connections to hosts in the local datacenter must be opened on connect. Default: true.

Declaration

public PoolingOptions SetWarmup(bool doWarmup)

Parameters

Type	Name	Description
bool	doWarmup

Returns

Type	Description
PoolingOptions