Struct scylla::transport::load_balancing::DefaultPolicyBuilder

pub struct DefaultPolicyBuilder { /* private fields */ }

The intended way to instantiate the DefaultPolicy.

Example

use scylla::load_balancing::DefaultPolicy;

let default_policy = DefaultPolicy::builder()
    .prefer_datacenter("dc1".to_string())
    .token_aware(true)
    .permit_dc_failover(true)
    .build();

Implementations

impl DefaultPolicyBuilder

pub fn new() -> Self

Creates a builder used to customise configuration of a new DefaultPolicy.

pub fn build(self) -> Arc<dyn LoadBalancingPolicy>

Builds a new DefaultPolicy with the previously set configuration.

pub fn prefer_datacenter(self, datacenter_name: String) -> Self

Sets the datacenter to be preferred by this policy.

Allows the load balancing policy to prioritize nodes based on their location. When a preferred datacenter is set, the policy will treat nodes in that datacenter as “local” nodes, and nodes in other datacenters as “remote” nodes. This affects the order in which nodes are returned by the policy when selecting replicas for read or write operations. If no preferred datacenter is specified, the policy will treat all nodes as local nodes.

When datacenter failover is disabled (permit_dc_failover is set to false), the default policy will only include local nodes in load balancing plans. Remote nodes will be excluded, even if they are alive and available to serve requests.

pub fn prefer_datacenter_and_rack( self, datacenter_name: String, rack_name: String, ) -> Self

Sets the datacenter and rack to be preferred by this policy.

Allows the load balancing policy to prioritize nodes based on their location as well as their availability zones in the preferred datacenter. When a preferred datacenter is set, the policy will treat nodes in that datacenter as “local” nodes, and nodes in other datacenters as “remote” nodes. This affects the order in which nodes are returned by the policy when selecting replicas for read or write operations. If no preferred datacenter is specified, the policy will treat all nodes as local nodes.

When datacenter failover is disabled (permit_dc_failover is set to false), the default policy will only include local nodes in load balancing plans. Remote nodes will be excluded, even if they are alive and available to serve requests.

When a preferred rack is set, the policy will first return replicas in the local rack in the preferred datacenter, and then the other replicas in the datacenter.

pub fn token_aware(self, is_token_aware: bool) -> Self

Sets whether this policy is token-aware (balances load more consciously) or not.

Token awareness refers to a mechanism by which the driver is aware of the token range assigned to each node in the cluster. Tokens are assigned to nodes to partition the data and distribute it across the cluster.

When a user wants to read or write data, the driver can use token awareness to route the request to the correct node based on the token range of the data being accessed. This can help to minimize network traffic and improve performance by ensuring that the data is accessed locally as much as possible.

In the case of DefaultPolicy, token awareness is enabled by default, meaning that the policy will prefer to return alive local replicas if the token is available. This means that if the client is requesting data that falls within the token range of a particular node, the policy will try to route the request to that node first, assuming it is alive and responsive.

Token awareness can significantly improve the performance and scalability of applications built on Scylla. By using token awareness, users can ensure that data is accessed locally as much as possible, reducing network overhead and improving throughput.

pub fn permit_dc_failover(self, permit: bool) -> Self

Sets whether this policy permits datacenter failover, i.e. ever attempts to send requests to nodes from a non-preferred datacenter.

In the event of a datacenter outage or network failure, the nodes in that datacenter may become unavailable, and clients may no longer be able to access data stored on those nodes. To address this, the DefaultPolicy supports datacenter failover, which allows routing requests to nodes in other datacenters if the local nodes are unavailable.

Datacenter failover can be enabled in DefaultPolicy setting this flag. When it is set, the policy will prefer to return alive remote replicas if datacenter failover is permitted and possible due to consistency constraints.

pub fn latency_awareness( self, latency_awareness_builder: LatencyAwarenessBuilder, ) -> Self

Latency awareness is a mechanism that penalises nodes whose measured recent average latency classifies it as falling behind the others.

Every update_rate the global minimum average latency is computed, and all nodes whose average latency is worse than exclusion_threshold times the global minimum average latency become penalised for retry_period. Penalisation involves putting those nodes at the very end of the query plan. As it is often not truly beneficial to prefer faster non-replica than replicas lagging behind the non-replicas, this mechanism may as well worsen latencies and/or throughput.

ATTENTION: using latency awareness is NOT recommended, unless prior benchmarks prove its beneficial impact on the specific workload’s performance. Use with caution.

pub fn enable_shuffling_replicas(self, enable: bool) -> Self

Sets whether this policy should shuffle replicas when token-awareness is enabled. Shuffling can help distribute the load over replicas, but can reduce the effectiveness of caching on the database side (e.g. for reads).

This option is enabled by default. If disabled, replicas will be chosen in some random order that is chosen when the load balancing policy is created and will not change over its lifetime.

Trait Implementations

impl Clone for DefaultPolicyBuilder

fn clone(&self) -> DefaultPolicyBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DefaultPolicyBuilder

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

Formats the value using the given formatter.

impl Default for DefaultPolicyBuilder

fn default() -> Self

Returns the “default value” for a type.