struct CassCluster
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.
void cass_cluster_free
( cluster )Frees a cluster instance.
CassError cass_cluster_set_contact_points
( cluster, 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”
CassError cass_cluster_set_contact_points_n
( cluster, contact_points, contact_points_length )Same as CassCluster::cass_cluster_set_contact_points, but with lengths for string parameters.
CassError cass_cluster_set_port
( cluster, port )Sets the port.
Default: 9042
void cass_cluster_set_ssl
( cluster, ssl )Sets the SSL context and enables SSL.
CassError cass_cluster_set_authenticator_callbacks
( cluster, exchange_callbacks, cleanup_callback, data )Sets custom authenticator
CassError cass_cluster_set_protocol_version
( cluster, protocol_version )Sets the protocol version. This will automatically downgrade to the lowest supported protocol version.
Default: 4
CassError cass_cluster_set_num_threads_io
( cluster, num_threads )Sets the number of IO threads. This is the number of threads that will handle query requests.
Default: 1
CassError cass_cluster_set_queue_size_io
( cluster, queue_size )Sets the size of the fixed size queue that stores pending requests.
Default: 8192
CassError cass_cluster_set_queue_size_event
( cluster, queue_size )Sets the size of the fixed size queue that stores events.
Default: 8192
CassError cass_cluster_set_queue_size_log
( cluster, queue_size )Sets the size of the fixed size queue that stores log messages.
Default: 8192
CassError cass_cluster_set_core_connections_per_host
( cluster, num_connections )Sets the number of connections made to each server in each IO thread.
Default: 1
CassError cass_cluster_set_max_connections_per_host
( cluster, num_connections )Sets the maximum number of connections made to each server in each IO thread.
Default: 2
void cass_cluster_set_reconnect_wait_time
( cluster, wait_time )Sets the amount of time to wait before attempting to reconnect.
Default: 2000 milliseconds
CassError cass_cluster_set_max_concurrent_creation
( cluster, 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
CassError cass_cluster_set_max_concurrent_requests_threshold
( cluster, 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
CassError cass_cluster_set_max_requests_per_flush
( cluster, num_requests )Sets the maximum number of requests processed by an IO worker per flush.
Default: 128
CassError cass_cluster_set_write_bytes_high_water_mark
( cluster, 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
CassError cass_cluster_set_write_bytes_low_water_mark
( cluster, 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
CassError cass_cluster_set_pending_requests_high_water_mark
( cluster, 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: 256
CassError cass_cluster_set_pending_requests_low_water_mark
( cluster, 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: 128
void cass_cluster_set_connect_timeout
( cluster, timeout_ms )Sets the timeout for connecting to a node.
Default: 5000 milliseconds
void cass_cluster_set_request_timeout
( cluster, timeout_ms )Sets the timeout for waiting for a response from a node.
Default: 12000 milliseconds
void cass_cluster_set_resolve_timeout
( cluster, timeout_ms )Sets the timeout for waiting for DNS name resolution.
Default: 2000 milliseconds
void cass_cluster_set_credentials
( cluster, username, password )Sets credentials for plain text authentication.
void cass_cluster_set_credentials_n
( cluster, username, username_length, password, password_length )Same as CassCluster::cass_cluster_set_credentials, but with lengths for string parameters.
void cass_cluster_set_load_balance_round_robin
( 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’.
CassError cass_cluster_set_load_balance_dc_aware
( cluster, local_dc, used_hosts_per_remote_dc, 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.
CassError cass_cluster_set_load_balance_dc_aware_n
( cluster, local_dc, local_dc_length, used_hosts_per_remote_dc, allow_remote_dcs_for_local_cl )Same as CassCluster::cass_cluster_set_load_balance_dc_aware, but with lengths for string parameters.
void cass_cluster_set_token_aware_routing
( cluster, enabled )Configures the cluster to use token-aware request routing or not.
Important: Token-aware routing depends on keyspace metadata. For this reason enabling token-aware routing will also enable retrieving and updating keyspace schema metadata.
Default: 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.
void cass_cluster_set_latency_aware_routing
( cluster, enabled )Configures the cluster to use latency-aware request routing or not.
Default: 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.
void cass_cluster_set_latency_aware_routing_settings
( cluster, exclusion_threshold, scale_ms, retry_period_ms, update_rate_ms, 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
void cass_cluster_set_whitelist_filtering
( cluster, hosts )Sets/Appends whitelist hosts. The first call sets the whitelist hosts and any subsequent calls appends additional hosts. Passing an empty string will clear and disable the whitelist. White space is striped from the hosts.
This policy filters requests to all other policies, only allowing requests to the hosts contained in the whitelist. Any host not in the whitelist will be ignored and a connection will not be established. This policy is useful for ensuring that the driver will only connect to a predefined set of hosts.
Examples: “127.0.0.1” “127.0.0.1,127.0.0.2”
void cass_cluster_set_whitelist_filtering_n
( cluster, hosts, hosts_length )Same as cass_cluster_set_whitelist_filtering_hosts(), but with lengths for string parameters.
void cass_cluster_set_blacklist_filtering
( cluster, hosts )Sets/Appends blacklist hosts. The first call sets the blacklist hosts and any subsequent calls appends additional hosts. Passing an empty string will clear and disable the blacklist. White space is striped from the hosts.
This policy filters requests to all other policies, only allowing requests to the hosts not contained in the blacklist. Any host in the blacklist will be ignored and a connection will not be established. This policy is useful for ensuring that the driver will not connect to a predefined set of hosts.
Examples: “127.0.0.1” “127.0.0.1,127.0.0.2”
void cass_cluster_set_blacklist_filtering_n
( cluster, hosts, hosts_length )Same as cass_cluster_set_blacklist_filtering_hosts(), but with lengths for string parameters.
void cass_cluster_set_whitelist_dc_filtering
( cluster, dcs )Same as CassCluster::cass_cluster_set_whitelist_filtering, but whitelist all hosts of a dc
Examples: “dc1”, “dc1,dc2”
void cass_cluster_set_whitelist_dc_filtering_n
( cluster, dcs, dcs_length )Same as CassCluster::cass_cluster_set_whitelist_dc_filtering, but with lengths for string parameters.
void cass_cluster_set_blacklist_dc_filtering
( cluster, dcs )Same as CassCluster::cass_cluster_set_blacklist_filtering, but blacklist all hosts of a dc
Examples: “dc1”, “dc1,dc2”
void cass_cluster_set_blacklist_dc_filtering_n
( cluster, dcs, dcs_length )Same as CassCluster::cass_cluster_set_blacklist_dc_filtering, but with lengths for string parameters.
void cass_cluster_set_tcp_nodelay
( cluster, enabled )Enable/Disable Nagel’s algorithm on connections.
Default: cass_true (disables Nagel’s algorithm).
void cass_cluster_set_tcp_keepalive
( cluster, enabled, delay_secs )Enable/Disable TCP keep-alive
Default: cass_false (disabled).
void cass_cluster_set_timestamp_gen
( cluster, timestamp_gen )Sets the timestamp generator used to assign timestamps to all requests unless overridden by setting the timestamp on a statement or a batch.
Default: server-side timestamp generator.
Requires Cassandra: 2.1+
void cass_cluster_set_connection_heartbeat_interval
( cluster, interval_secs )Sets the amount of time between heartbeat messages and controls the amount of time the connection must be idle before sending heartbeat messages. This is useful for preventing intermediate network devices from dropping connections.
Default: 30 seconds
void cass_cluster_set_connection_idle_timeout
( cluster, timeout_secs )Sets the amount of time a connection is allowed to be without a successful heartbeat response before being terminated and scheduled for reconnection.
Default: 60 seconds
void cass_cluster_set_retry_policy
( cluster, retry_policy )Sets the retry policy used for all requests unless overridden by setting a retry policy on a statement or a batch.
Default: The same policy as would be created by the function: CassRetryPolicy::cass_retry_policy_default_new. This policy will retry on a read timeout if there was enough replicas, but no data present, on a write timeout if a logged batch request failed to write the batch log, and on a unavailable error it retries using a new host. In all other cases the default policy will return an error.
void cass_cluster_set_use_schema
( cluster, enabled )Enable/Disable retrieving and updating schema metadata. If disabled this is allows the driver to skip over retrieving and updating schema metadata and CassSession::cass_session_get_schema_meta will always return an empty object. This can be useful for reducing the startup overhead of short-lived sessions.
Default: cass_true (enabled).
CassError cass_cluster_set_use_hostname_resolution
( cluster, enabled )Enable/Disable retrieving hostnames for IP addresses using reverse IP lookup.
This is useful for authentication (Kerberos) or encryption (SSL) services that require a valid hostname for verification.
Default: cass_false (disabled).
Important: Not implemented if using libuv 0.1x or earlier
CassError cass_cluster_set_use_randomized_contact_points
( cluster, enabled )Enable/Disable the randomization of the contact points list.
Default: cass_true (enabled).
Important: This setting should only be disabled for debugging or tests.