A cluster object describes the configuration of the Cassandra cluster and is used to construct a session instance. Unlike other DataStax drivers the cluster object does not maintain the control connection.

Functions

CassCluster *

cass_cluster_new

( )

Creates a new cluster.

Returns:
Type Details
CassCluster *

Returns a cluster that must be freed.

See Also:
void

cass_cluster_free

( CassCluster * cluster )

Frees a cluster instance.

Parameters:
Name Type Details
in cluster CassCluster *
CassError

cass_cluster_set_contact_points

( CassCluster * cluster, const char * contact_points )

Sets/Appends contact points. This MUST be set. The first call sets the contact points and any subsequent calls appends additional contact points. Passing an empty string will clear the contact points. White space is striped from the contact points.

Examples: “127.0.0.1” “127.0.0.1,127.0.0.2”, “server1.domain.com”

Parameters:
Name Type Details
in cluster CassCluster *
in contact_points const char *

A comma delimited list of addresses or names. An empty string will clear the contact points. The string is copied into the cluster configuration; the memory pointed to by this parameter can be freed after this call.

Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_contact_points_n

( CassCluster * cluster, const char * contact_points, size_t contact_points_length )

Same as CassCluster::cass_cluster_set_contact_points, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in contact_points const char *
in contact_points_length size_t
Returns:
Type Details
CassError

same as CassCluster::cass_cluster_set_contact_points

See Also:
CassError

cass_cluster_set_port

( CassCluster * cluster, int port )

Sets the port.

Default: 9042

Parameters:
Name Type Details
in cluster CassCluster *
in port int
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

void

cass_cluster_set_ssl

( CassCluster * cluster, CassSsl * ssl )

Sets the SSL context and enables SSL.

Parameters:
Name Type Details
in cluster CassCluster *
in ssl CassSsl *
See Also:
CassError

cass_cluster_set_protocol_version

( CassCluster * cluster, int protocol_version )

Sets the protocol version. This will automatically downgrade if to protocol version 1.

Default: 2

Parameters:
Name Type Details
in cluster CassCluster *
in protocol_version int
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_num_threads_io

( CassCluster * cluster, unsigned num_threads )

Sets the number of IO threads. This is the number of threads that will handle query requests.

Default: 1

Parameters:
Name Type Details
in cluster CassCluster *
in num_threads unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_queue_size_io

( CassCluster * cluster, unsigned queue_size )

Sets the size of the the fixed size queue that stores pending requests.

Default: 4096

Parameters:
Name Type Details
in cluster CassCluster *
in queue_size unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_queue_size_event

( CassCluster * cluster, unsigned queue_size )

Sets the size of the the fixed size queue that stores events.

Default: 4096

Parameters:
Name Type Details
in cluster CassCluster *
in queue_size unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_queue_size_log

( CassCluster * cluster, unsigned queue_size )

Sets the size of the the fixed size queue that stores log messages.

Default: 4096

Parameters:
Name Type Details
in cluster CassCluster *
in queue_size unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_core_connections_per_host

( CassCluster * cluster, unsigned num_connections )

Sets the number of connections made to each server in each IO thread.

Default: 1

Parameters:
Name Type Details
in cluster CassCluster *
in num_connections unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_max_connections_per_host

( CassCluster * cluster, unsigned num_connections )

Sets the maximum number of connections made to each server in each IO thread.

Default: 2

Parameters:
Name Type Details
in cluster CassCluster *
in num_connections unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

void

cass_cluster_set_reconnect_wait_time

( CassCluster * cluster, unsigned wait_time )

Sets the amount of time to wait before attempting to reconnect.

Default: 2000 milliseconds

Parameters:
Name Type Details
in cluster CassCluster *
in wait_time unsigned
CassError

cass_cluster_set_max_concurrent_creation

( CassCluster * cluster, unsigned num_connections )

Sets the maximum number of connections that will be created concurrently. Connections are created when the current connections are unable to keep up with request throughput.

Default: 1

Parameters:
Name Type Details
in cluster CassCluster *
in num_connections unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_max_concurrent_requests_threshold

( CassCluster * cluster, unsigned num_requests )

Sets the threshold for the maximum number of concurrent requests in-flight on a connection before creating a new connection. The number of new connections created will not exceed max_connections_per_host.

Default: 100

Parameters:
Name Type Details
in cluster CassCluster *
in num_requests unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_max_requests_per_flush

( CassCluster * cluster, unsigned num_requests )

Sets the maximum number of requests processed by an IO worker per flush.

Default: 128

Parameters:
Name Type Details
in cluster CassCluster *
in num_requests unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_write_bytes_high_water_mark

( CassCluster * cluster, unsigned num_bytes )

Sets the high water mark for the number of bytes outstanding on a connection. Disables writes to a connection if the number of bytes queued exceed this value.

Default: 64 KB

Parameters:
Name Type Details
in cluster CassCluster *
in num_bytes unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_write_bytes_low_water_mark

( CassCluster * cluster, unsigned num_bytes )

Sets the low water mark for number of bytes outstanding on a connection. After exceeding high water mark bytes, writes will only resume once the number of bytes fall below this value.

Default: 32 KB

Parameters:
Name Type Details
in cluster CassCluster *
in num_bytes unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_pending_requests_high_water_mark

( CassCluster * cluster, unsigned num_requests )

Sets the high water mark for the number of requests queued waiting for a connection in a connection pool. Disables writes to a host on an IO worker if the number of requests queued exceed this value.

Default: 128 * max_connections_per_host

Parameters:
Name Type Details
in cluster CassCluster *
in num_requests unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

CassError

cass_cluster_set_pending_requests_low_water_mark

( CassCluster * cluster, unsigned num_requests )

Sets the low water mark for the number of requests queued waiting for a connection in a connection pool. After exceeding high water mark requests, writes to a host will only resume once the number of requests fall below this value.

Default: 64 * max_connections_per_host

Parameters:
Name Type Details
in cluster CassCluster *
in num_requests unsigned
Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred.

void

cass_cluster_set_connect_timeout

( CassCluster * cluster, unsigned timeout_ms )

Sets the timeout for connecting to a node.

Default: 5000 milliseconds

Parameters:
Name Type Details
in cluster CassCluster *
in timeout_ms unsigned

Connect timeout in milliseconds

void

cass_cluster_set_request_timeout

( CassCluster * cluster, unsigned timeout_ms )

Sets the timeout for waiting for a response from a node.

Default: 12000 milliseconds

Parameters:
Name Type Details
in cluster CassCluster *
in timeout_ms unsigned

Request timeout in milliseconds

void

cass_cluster_set_credentials

( CassCluster * cluster, const char * username, const char * password )

Sets credentials for plain text authentication.

Parameters:
Name Type Details
in cluster CassCluster *
in username const char *
in password const char *
void

cass_cluster_set_credentials_n

( CassCluster * cluster, const char * username, size_t username_length, const char * password, size_t password_length )

Same as CassCluster::cass_cluster_set_credentials, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in username const char *
in username_length size_t
in password const char *
in password_length size_t
Returns:
Type Details
void

same as CassCluster::cass_cluster_set_credentials

See Also:
void

cass_cluster_set_load_balance_round_robin

( CassCluster * cluster )

Configures the cluster to use round-robin load balancing.

The driver discovers all nodes in a cluster and cycles through them per request. All are considered ‘local’.

Parameters:
Name Type Details
in cluster CassCluster *
CassError

cass_cluster_set_load_balance_dc_aware

( CassCluster * cluster, const char * local_dc, unsigned used_hosts_per_remote_dc, cass_bool_t allow_remote_dcs_for_local_cl )

Configures the cluster to use DC-aware load balancing. For each query, all live nodes in a primary ‘local’ DC are tried first, followed by any node from other DCs.

Note: This is the default, and does not need to be called unless switching an existing from another policy or changing settings. Without further configuration, a default local_dc is chosen from the first connected contact point, and no remote hosts are considered in query plans. If relying on this mechanism, be sure to use only contact points from the local DC.

Parameters:
Name Type Details
in cluster CassCluster *
in local_dc const char *

The primary data center to try first

in used_hosts_per_remote_dc unsigned

The number of host used in each remote DC if no hosts are available in the local dc

in allow_remote_dcs_for_local_cl cass_bool_t

Allows remote hosts to be used if no local dc hosts are available and the consistency level is LOCAL_ONE or LOCAL_QUORUM

Returns:
Type Details
CassError

CASS_OK if successful, otherwise an error occurred

CassError

cass_cluster_set_load_balance_dc_aware_n

( CassCluster * cluster, const char * local_dc, size_t local_dc_length, unsigned used_hosts_per_remote_dc, cass_bool_t allow_remote_dcs_for_local_cl )

Same as CassCluster::cass_cluster_set_load_balance_dc_aware, but with lengths for string parameters.

Parameters:
Name Type Details
in cluster CassCluster *
in local_dc const char *
in local_dc_length size_t
in used_hosts_per_remote_dc unsigned
in allow_remote_dcs_for_local_cl cass_bool_t
Returns:
Type Details
CassError

same as CassCluster::cass_cluster_set_load_balance_dc_aware

See Also:
void

cass_cluster_set_token_aware_routing

( CassCluster * cluster, cass_bool_t enabled )

Configures the cluster to use token-aware request routing, or not.

Default is cass_true (enabled).

This routing policy composes the base routing policy, routing requests first to replicas on nodes considered ‘local’ by the base load balancing policy.

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
void

cass_cluster_set_latency_aware_routing

( CassCluster * cluster, cass_bool_t enabled )

Configures the cluster to use latency-aware request routing, or not.

Default is cass_false (disabled).

This routing policy is a top-level routing policy. It uses the base routing policy to determine locality (dc-aware) and/or placement (token-aware) before considering the latency.

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
void

cass_cluster_set_latency_aware_routing_settings

( CassCluster * cluster, cass_double_t exclusion_threshold, cass_uint64_t scale_ms, cass_uint64_t retry_period_ms, cass_uint64_t update_rate_ms, cass_uint64_t min_measured )

Configures the settings for latency-aware request routing.

Defaults:

  • exclusion_threshold: 2.0
  • scale_ms: 100 milliseconds
  • retry_period_ms: 10,000 milliseconds (10 seconds)
  • update_rate_ms: 100 milliseconds
  • min_measured: 50
Parameters:
Name Type Details
in cluster CassCluster *
in exclusion_threshold cass_double_t

Controls how much worse the latency must be compared to the average latency of the best performing node before it penalized.

in scale_ms cass_uint64_t

Controls the weight given to older latencies when calculating the average latency of a node. A bigger scale will give more weight to older latency measurements.

in retry_period_ms cass_uint64_t

The amount of time a node is penalized by the policy before being given a second chance when the current average latency exceeds the calculated threshold (exclusion_threshold * best_average_latency).

in update_rate_ms cass_uint64_t

The rate at which the best average latency is recomputed.

in min_measured cass_uint64_t

The minimum number of measurements per-host required to be considered by the policy.

void

cass_cluster_set_tcp_nodelay

( CassCluster * cluster, cass_bool_t enabled )

Enable/Disable Nagel’s algorithm on connections.

Default: cass_false (disabled).

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
void

cass_cluster_set_tcp_keepalive

( CassCluster * cluster, cass_bool_t enabled, unsigned delay_secs )

Enable/Disable TCP keep-alive

Default: cass_false (disabled).

Parameters:
Name Type Details
in cluster CassCluster *
in enabled cass_bool_t
in delay_secs unsigned

The initial delay in seconds, ignored when enabled is false.