-
Notifications
You must be signed in to change notification settings - Fork 184
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
loadbalancer-experimental: adjust load balancer policy docs and helpe…
…rs (#2926) Motivation: - More detail could be provided for the P2C and RR `failOpen` configuration option since it might not be clear what fail-open mean in that context. - We could use some helpers to make the different policies more discoverable. Modifications: - Adjust the docs for `.failOpen` to add more detail. - Add LoadBalancerPolicies to aid discoverability of load balancer policies. - Move away from `new *Builder` pattern and add deprecations.
- Loading branch information
1 parent
dd37c3b
commit f0e7aff
Showing
14 changed files
with
273 additions
and
29 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
48 changes: 48 additions & 0 deletions
48
...balancer-experimental/src/main/java/io/servicetalk/loadbalancer/LoadBalancerPolicies.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| /* | ||
| * Copyright © 2023 Apple Inc. and the ServiceTalk project authors | ||
| * | ||
| * Licensed under the Apache License, Version 2.0 (the "License"); | ||
| * you may not use this file except in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * http://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, software | ||
| * distributed under the License is distributed on an "AS IS" BASIS, | ||
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| * See the License for the specific language governing permissions and | ||
| * limitations under the License. | ||
| */ | ||
| package io.servicetalk.loadbalancer; | ||
|
|
||
| /** | ||
| * A collections of factories for constructing a {@link LoadBalancingPolicy}. | ||
| */ | ||
| public final class LoadBalancerPolicies { | ||
|
|
||
| private LoadBalancerPolicies() { | ||
| // no instances. | ||
| } | ||
|
|
||
| /** | ||
| * Builder for the round-robin {@link LoadBalancingPolicy}. | ||
| * Round-robin load balancing is a strategy that maximizes fairness of the request distribution. This comes at the | ||
| * cost of being unable to bias toward better performing hosts and can only leverage the course grained | ||
| * healthy/unhealthy status of a host. | ||
| * @return a builder for the round-robin {@link LoadBalancingPolicy}. | ||
| */ | ||
| public static RoundRobinLoadBalancingPolicyBuilder roundRobin() { | ||
| return new RoundRobinLoadBalancingPolicyBuilder(); | ||
| } | ||
|
|
||
| /** | ||
| * Builder for the power of two choices (P2C) {@link LoadBalancingPolicy}. | ||
| * Power of Two Choices (P2C) leverages both course grained healthy/unhealthy status of a host plus additional | ||
| * fine-grained scoring to prioritize hosts that are both healthy and better performing. See the | ||
| * {@link P2CLoadBalancingPolicy} for more details. | ||
| * @return a builder for the power of two choices (P2C) {@link LoadBalancingPolicy}. | ||
| */ | ||
| public static P2CLoadBalancingPolicyBuilder p2c() { | ||
| return new P2CLoadBalancingPolicyBuilder(); | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
105 changes: 105 additions & 0 deletions
105
...experimental/src/main/java/io/servicetalk/loadbalancer/P2CLoadBalancingPolicyBuilder.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,105 @@ | ||
| /* | ||
| * Copyright © 2024 Apple Inc. and the ServiceTalk project authors | ||
| * | ||
| * Licensed under the Apache License, Version 2.0 (the "License"); | ||
| * you may not use this file except in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * http://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, software | ||
| * distributed under the License is distributed on an "AS IS" BASIS, | ||
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| * See the License for the specific language governing permissions and | ||
| * limitations under the License. | ||
| */ | ||
| package io.servicetalk.loadbalancer; | ||
|
|
||
| import io.servicetalk.client.api.LoadBalancedConnection; | ||
|
|
||
| import java.util.Random; | ||
| import javax.annotation.Nullable; | ||
|
|
||
| import static io.servicetalk.utils.internal.NumberUtils.ensurePositive; | ||
|
|
||
| /** | ||
| * A builder for immutable {@link P2CLoadBalancingPolicy} instances. | ||
| * @see LoadBalancerPolicies#p2c() | ||
| */ | ||
| public final class P2CLoadBalancingPolicyBuilder { | ||
|
|
||
| private static final boolean DEFAULT_IGNORE_WEIGHTS = false; | ||
| private static final int DEFAULT_MAX_EFFORT = 5; | ||
| private static final boolean DEFAULT_FAIL_OPEN_POLICY = LoadBalancingPolicy.DEFAULT_FAIL_OPEN_POLICY; | ||
|
|
||
| private boolean ignoreWeights = DEFAULT_IGNORE_WEIGHTS; | ||
| private int maxEffort = DEFAULT_MAX_EFFORT; | ||
| private boolean failOpen = DEFAULT_FAIL_OPEN_POLICY; | ||
| @Nullable | ||
| private Random random; | ||
|
|
||
| P2CLoadBalancingPolicyBuilder() { | ||
| // package private | ||
| } | ||
|
|
||
| /** | ||
| * Set the maximum number of attempts that P2C will attempt to select a pair with at least one | ||
| * healthy host. | ||
| * Defaults to {@value DEFAULT_MAX_EFFORT}. | ||
| * | ||
| * @param maxEffort the maximum number of attempts. | ||
| * @return {@code this} | ||
| */ | ||
| public P2CLoadBalancingPolicyBuilder maxEffort(final int maxEffort) { | ||
| this.maxEffort = ensurePositive(maxEffort, "maxEffort"); | ||
| return this; | ||
| } | ||
|
|
||
| /** | ||
| * Set whether the selector should fail-open in the event no healthy hosts are found. | ||
| * When a load balancing policy is configured to fail-open and is unable to find a healthy host, it will attempt | ||
| * to select or establish a connection from an arbitrary host even if it is unlikely to return a healthy | ||
| * session. | ||
| * Defaults to {@value DEFAULT_FAIL_OPEN_POLICY}. | ||
| * | ||
| * @param failOpen if true, will attempt to select or establish a connection from an arbitrary host even if it | ||
| * is unlikely to return a healthy session. | ||
| * @return {@code this} | ||
| */ | ||
| public P2CLoadBalancingPolicyBuilder failOpen(final boolean failOpen) { | ||
| this.failOpen = failOpen; | ||
| return this; | ||
| } | ||
|
|
||
| /** | ||
| * Set whether the host selector should ignore {@link Host}s weight. | ||
| * Host weight influences the probability it will be selected to serve a request. The host weight can come | ||
| * from many sources including known host capacity, priority groups, and others, so ignoring weight | ||
| * information can lead to other features not working properly and should be used with care. | ||
| * Defaults to {@value DEFAULT_IGNORE_WEIGHTS}. | ||
| * | ||
| * @param ignoreWeights whether the host selector should ignore host weight information. | ||
| * @return {@code this} | ||
| */ | ||
| public P2CLoadBalancingPolicyBuilder ignoreWeights(final boolean ignoreWeights) { | ||
| this.ignoreWeights = ignoreWeights; | ||
| return this; | ||
| } | ||
|
|
||
| // For testing purposes only. | ||
| P2CLoadBalancingPolicyBuilder random(Random random) { | ||
| this.random = random; | ||
| return this; | ||
| } | ||
|
|
||
| /** | ||
| * Construct an immutable {@link P2CLoadBalancingPolicy}. | ||
| * | ||
| * @param <ResolvedAddress> the type of the resolved address. | ||
| * @param <C> the refined type of the {@link LoadBalancedConnection}. | ||
| * @return the concrete {@link P2CLoadBalancingPolicy}. | ||
| */ | ||
| public <ResolvedAddress, C extends LoadBalancedConnection> LoadBalancingPolicy<ResolvedAddress, C> build() { | ||
| return new P2CLoadBalancingPolicy<>(ignoreWeights, maxEffort, failOpen, random); | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
78 changes: 78 additions & 0 deletions
78
...ental/src/main/java/io/servicetalk/loadbalancer/RoundRobinLoadBalancingPolicyBuilder.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| /* | ||
| * Copyright © 2024 Apple Inc. and the ServiceTalk project authors | ||
| * | ||
| * Licensed under the Apache License, Version 2.0 (the "License"); | ||
| * you may not use this file except in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * http://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, software | ||
| * distributed under the License is distributed on an "AS IS" BASIS, | ||
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| * See the License for the specific language governing permissions and | ||
| * limitations under the License. | ||
| */ | ||
| package io.servicetalk.loadbalancer; | ||
|
|
||
| import io.servicetalk.client.api.LoadBalancedConnection; | ||
|
|
||
| /** | ||
| * A builder for immutable {@link RoundRobinLoadBalancingPolicy} instances. | ||
| * @see LoadBalancerPolicies#roundRobin() | ||
| */ | ||
| public final class RoundRobinLoadBalancingPolicyBuilder { | ||
|
|
||
| private static final boolean DEFAULT_IGNORE_WEIGHTS = false; | ||
| private static final boolean DEFAULT_FAIL_OPEN_POLICY = LoadBalancingPolicy.DEFAULT_FAIL_OPEN_POLICY; | ||
|
|
||
| private boolean failOpen = DEFAULT_FAIL_OPEN_POLICY; | ||
| private boolean ignoreWeights = DEFAULT_IGNORE_WEIGHTS; | ||
|
|
||
| RoundRobinLoadBalancingPolicyBuilder() { | ||
| // package private constructor | ||
| } | ||
|
|
||
| /** | ||
| * Set whether the selector should fail-open in the event no healthy hosts are found. | ||
| * When a load balancing policy is configured to fail-open and is unable to find a healthy host, it will attempt | ||
| * to select or establish a connection from an arbitrary host even if it is unlikely to return a healthy | ||
| * session. | ||
| * Defaults to {@value DEFAULT_FAIL_OPEN_POLICY}. | ||
| * | ||
| * @param failOpen if true, will attempt to select or establish a connection from an arbitrary host even if it | ||
| * is unlikely to return a healthy session. | ||
| * @return {@code this} | ||
| */ | ||
| public RoundRobinLoadBalancingPolicyBuilder failOpen(final boolean failOpen) { | ||
| this.failOpen = failOpen; | ||
| return this; | ||
| } | ||
|
|
||
| /** | ||
| * Set whether the host selector should ignore {@link Host}s weight. | ||
| * Host weight influences the probability it will be selected to serve a request. The host weight can come | ||
| * from many sources including known host capacity, priority groups, and others, so ignoring weight | ||
| * information can lead to other features not working properly and should be used with care. | ||
| * Defaults to {@value DEFAULT_IGNORE_WEIGHTS}. | ||
| * | ||
| * @param ignoreWeights whether the host selector should ignore host weight information. | ||
| * @return {@code this} | ||
| */ | ||
| public RoundRobinLoadBalancingPolicyBuilder ignoreWeights(final boolean ignoreWeights) { | ||
| this.ignoreWeights = ignoreWeights; | ||
| return this; | ||
| } | ||
|
|
||
| /** | ||
| * Construct the immutable {@link RoundRobinLoadBalancingPolicy}. | ||
| * | ||
| * @param <ResolvedAddress> the type of the resolved address. | ||
| * @param <C> the refined type of the {@link LoadBalancedConnection}. | ||
| * @return the concrete {@link RoundRobinLoadBalancingPolicy}. | ||
| */ | ||
| public <ResolvedAddress, C extends LoadBalancedConnection> LoadBalancingPolicy<ResolvedAddress, C> | ||
| build() { | ||
| return new RoundRobinLoadBalancingPolicy<>(failOpen, ignoreWeights); | ||
| } | ||
| } |
Oops, something went wrong.