Struct Cluster

pub struct Cluster(/* private fields */);

The main class to use when interacting with a Cassandra cluster. Typically, one instance of this class will be created for each separate Cassandra cluster that your application interacts with.

Examples

use cassandra_cpp::Cluster;
let mut cluster = Cluster::default();
cluster.set_contact_points("127.0.0.1").unwrap();
let session = cluster.connect().await.unwrap();

Implementations

impl Cluster

pub fn set_contact_points(&mut self, contact_points: &str) -> Result<&mut Self>

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 stripped from the contact points.

{contact points: “127.0.0.1” “127.0.0.1,127.0.0.2”, “server1.domain.com”}

pub fn set_local_address(&mut self, name: &str) -> Result<&mut Self>

Sets the local address to bind when connecting to the cluster, if desired.

Only numeric addresses are supported.

pub fn set_port(&mut self, port: u16) -> Result<&mut Self>

Sets the port

Default: 9042

pub fn set_ssl(&mut self, ssl: Ssl) -> &Self

Sets the SSL context and enables SSL

pub fn set_cloud_secure_connection_bundle( &mut self, path: &str, ) -> Result<&mut Self>

Sets the secure connection bundle path for processing DBaaS credentials.

pub fn set_cloud_secure_connection_bundle_no_ssl_lib_init( &mut self, path: &str, ) -> Result<&mut Self>

Sets the secure connection bundle path for processing DBaaS credentials, but it does not initialize the underlying SSL library implementation. The SSL library still needs to be initialized, but it’s up to the client application to handle initialization.

pub async fn connect(&mut self) -> Result<Session>

Connects to the cassandra cluster

pub async fn connect_keyspace(&mut self, keyspace: &str) -> Result<Session>

Connects to the cassandra cluster, setting the keyspace of the session.

pub fn set_protocol_version( &mut self, protocol_version: CqlProtocol, ) -> Result<&mut Self>

Sets the protocol version. This will automatically downgrade to the lowest supported protocol version.

Default: version 4

pub fn set_num_threads_io(&mut self, num_threads: u32) -> Result<&mut Self>

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

Default: 1

pub fn set_queue_size_io(&mut self, queue_size: u32) -> Result<&mut Self>

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

Default: 8192

pub fn set_queue_size_event(&mut self, queue_size: u32) -> Result<&mut Self>

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

Default: 8192

pub fn set_core_connections_per_host( &mut self, num_connections: u32, ) -> Result<&mut Self>

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

Default: 1

pub fn set_max_connections_per_host( &mut self, num_connections: u32, ) -> Result<&mut Self>

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

Default: 2

pub fn set_reconnect_wait_time(&mut self, wait_time: u32) -> &Self

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

Default: 1000ms

pub fn set_max_concurrent_creation( &mut self, num_connections: u32, ) -> Result<&mut Self>

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

pub fn set_max_concurrent_requests_threshold( &mut self, num_requests: u32, ) -> Result<&mut Self>

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

pub fn set_max_requests_per_flush( &mut self, num_requests: u32, ) -> Result<&mut Self>

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

Default: 128

pub fn set_write_bytes_high_water_mark( &mut self, num_bytes: u32, ) -> Result<&mut Self>

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: 64KB

pub fn set_write_bytes_low_water_mark( &mut self, num_bytes: u32, ) -> Result<&mut Self>

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

Default: 32KB

pub fn set_pending_requests_high_water_mark( &mut self, num_requests: u32, ) -> Result<&mut Self>

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

pub fn set_pending_requests_low_water_mark( &mut self, num_requests: u32, ) -> Result<&mut Self>

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

pub fn set_connect_timeout(&mut self, timeout: Duration) -> &Self

Sets the timeout for connecting to a node.

Default: 5000ms

pub fn set_request_timeout(&mut self, timeout: Duration) -> &Self

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

Default: 12000ms

pub fn set_resolve_timeout(&mut self, timeout: Duration) -> &Self

Sets the timeout for resolving the host. Note: the default timeout when doing dns resolution with resolv.conf (as is done here) is 5000ms. When using the default cassandra-cpp-driver timeout (also 5000ms) then DNS resolution will fail before attempting to query backup DNS servers.

Default: 5000ms

pub fn set_exponential_reconnect( &mut self, base_delay_ms: Duration, max_delay_ms: Duration, ) -> &Self

Configures the cluster to use a reconnection policy that waits exponentially longer between each reconnection attempt; however will maintain a constant delay once the maximum delay is reached.

This is the default reconnection policy.

Default:

• base_delay_ms: 2000ms
• max_delay_ms: 600000ms (10 minutes)

Note: A random amount of jitter (+/- 15%) will be added to the pure exponential delay value. This helps to prevent situations where multiple connections are in the reconnection process at exactly the same time. The jitter will never cause the delay to be less than the base delay, or more than the max delay.

pub fn set_credentials( &mut self, username: &str, password: &str, ) -> Result<&mut Self>

Sets credentials for plain text authentication.

pub fn set_load_balance_round_robin(&mut self) -> &Self

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’.

pub fn set_load_balance_dc_aware<S>( &mut self, local_dc: &str, used_hosts_per_remote_dc: u32, allow_remote_dcs_for_local_cl: bool, ) -> Result<&mut Self>

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.

pub fn set_token_aware_routing(&mut self, enabled: bool) -> &Self

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

Important: Token-aware routing depends on keyspace information. For this reason enabling token-aware routing will also enable the usage of schema metadata.

Default: 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.

pub fn set_token_aware_routing_shuffle_replicas( &mut self, enabled: bool, ) -> &Self

Configures token-aware routing to randomly shuffle replicas. This can reduce the effectiveness of server-side caching, but it can better distribute load over replicas for a given partition key.

Default: true (enabled)

Note: Token-aware routing must be enabled for the setting to be applicable.

pub fn set_latency_aware_routing(&mut self, enabled: bool) -> &Self

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

Default: 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.

pub fn set_latency_aware_routing_settings( &mut self, exclusion_threshold: f64, scale: Duration, retry_period: Duration, update_rate: Duration, min_measured: u64, ) -> &Self

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

pub fn set_whitelist_filtering(&mut self, hosts: Vec<String>) -> &Self

/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”, “server1.domain.com”

pub fn set_tcp_nodelay(&mut self, enable: bool) -> &Self

Enable/Disable Nagel’s algorithm on connections.

Default: true (disables Nagel’s algorithm).

pub fn set_tcp_keepalive(&mut self, enable: bool, delay: Duration) -> &Self

Enable/Disable TCP keep-alive

Default: false (disabled).

pub fn set_timestamp_gen(&mut self, tsg: &TimestampGen) -> &mut Self

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.

pub fn set_connection_heartbeat_interval( &mut self, hearbeat: Duration, ) -> &mut Self

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

pub fn set_connection_idle_timeout(&mut self, timeout: Duration) -> &mut Self

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

pub fn set_retry_policy(&mut self, retry_policy: RetryPolicy) -> &mut Self

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: 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.

pub fn set_use_schema(&mut self, enabled: bool) -> &Self

Enable/Disable retrieving and updating schema metadata. If disabled this is allows the driver to skip over retrieving and updating schema metadata, but it also disables the usage of token-aware routing and cass_session_get_schema() will always return an empty object. This can be useful for reducing the startup overhead of short-lived sessions.

Default: true (enabled).

Trait Implementations

impl Debug for Cluster

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Cluster

fn default() -> Cluster

Creates a new cluster

impl Drop for Cluster

fn drop(&mut self)

Frees a cluster instance.

impl Send for Cluster

impl Sync for Cluster