From 16dcc19c53b52df26b7b540c47a85d83e64ac16c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Wed, 13 Mar 2024 14:37:08 +0100 Subject: [PATCH] Docs: Informations about shard-aware LBPs This commit also includes some changes that were omitted during older changes to LBP. --- docs/source/load-balancing/load-balancing.md | 23 ++++++++++---------- scylla/src/transport/load_balancing/mod.rs | 11 +++++----- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/source/load-balancing/load-balancing.md b/docs/source/load-balancing/load-balancing.md index 5fc8a069c1..51bf88b1b7 100644 --- a/docs/source/load-balancing/load-balancing.md +++ b/docs/source/load-balancing/load-balancing.md @@ -2,8 +2,8 @@ ## Introduction -The driver uses a load balancing policy to determine which node(s) to contact -when executing a query. Load balancing policies implement the +The driver uses a load balancing policy to determine which node(s) and shard(s) +to contact when executing a query. Load balancing policies implement the `LoadBalancingPolicy` trait, which contains methods to generate a load balancing plan based on the query information and the state of the cluster. @@ -12,12 +12,14 @@ being opened. For a node connection blacklist configuration refer to `scylla::transport::host_filter::HostFilter`, which can be set session-wide using `SessionBuilder::host_filter` method. +In this chapter, "target" will refer to a pair ``. + ## Plan When a query is prepared to be sent to the database, the load balancing policy -constructs a load balancing plan. This plan is essentially a list of nodes to +constructs a load balancing plan. This plan is essentially a list of targets to which the driver will try to send the query. The first elements of the plan are -the nodes which are the best to contact (e.g. they might be replicas for the +the targets which are the best to contact (e.g. they might be replicas for the requested data or have the best latency). ## Policy @@ -84,15 +86,14 @@ first element of the load balancing plan is needed, so it's usually unnecessary to compute entire load balancing plan. To optimize this common case, the `LoadBalancingPolicy` trait provides two methods: `pick` and `fallback`. -`pick` returns the first node to contact for a given query, which is usually -the best based on a particular load balancing policy. If `pick` returns `None`, -then `fallback` will not be called. +`pick` returns the first target to contact for a given query, which is usually +the best based on a particular load balancing policy. -`fallback`, returns an iterator that provides the rest of the nodes in the load -balancing plan. `fallback` is called only when using the initial picked node -fails (or when executing speculatively). +`fallback`, returns an iterator that provides the rest of the targets in the +load balancing plan. `fallback` is called when using the initial picked +element fails (or when executing speculatively) or when `pick` returned `None`. -It's possible for the `fallback` method to include the same node that was +It's possible for the `fallback` method to include the same target that was returned by the `pick` method. In such cases, the query execution layer filters out the picked node from the iterator returned by `fallback`. diff --git a/scylla/src/transport/load_balancing/mod.rs b/scylla/src/transport/load_balancing/mod.rs index ad056a841f..9daf439162 100644 --- a/scylla/src/transport/load_balancing/mod.rs +++ b/scylla/src/transport/load_balancing/mod.rs @@ -41,16 +41,17 @@ pub struct RoutingInfo<'a> { /// (or when speculative execution is triggered). pub type FallbackPlan<'a> = Box, Shard)> + Send + Sync + 'a>; -/// Policy that decides which nodes to contact for each query. +/// Policy that decides which nodes and shards to contact for each query. /// /// When a query is prepared to be sent to ScyllaDB/Cassandra, a `LoadBalancingPolicy` -/// implementation constructs a load balancing plan. That plan is a list of nodes to which -/// the driver will try to send the query. The first elements of the plan are the nodes which are +/// implementation constructs a load balancing plan. That plan is a list of +/// targets (target is a node + an optional shard) to which +/// the driver will try to send the query. The first elements of the plan are the targets which are /// the best to contact (e.g. they might have the lowest latency). /// /// Most queries are send on the first try, so the query execution layer rarely needs to know more -/// than one node from plan. To better optimize that case, `LoadBalancingPolicy` has two methods: -/// `pick` and `fallback`. `pick` returns a first node to contact for a given query, `fallback` +/// than one target from plan. To better optimize that case, `LoadBalancingPolicy` has two methods: +/// `pick` and `fallback`. `pick` returns a first target to contact for a given query, `fallback` /// returns the rest of the load balancing plan. /// /// `fallback` is called not only if a send to `pick`ed node failed (or when executing