Package io.grpc.util

Class GracefulSwitchLoadBalancer

java.lang.Object

io.grpc.LoadBalancer

io.grpc.util.ForwardingLoadBalancer

io.grpc.util.GracefulSwitchLoadBalancer

@ExperimentalApi("https://github.com/grpc/grpc-java/issues/5999")
@NotThreadSafe
public final class GracefulSwitchLoadBalancer
extends ForwardingLoadBalancer

A load balancer that gracefully swaps to a new lb policy. If the channel is currently in a state other than READY, the new policy will be swapped into place immediately. Otherwise, the channel will keep using the old policy until the new policy reports READY or the old policy exits READY.

The child balancer and configuration is specified using service config. Config objects are generally created by calling parseLoadBalancingPolicyConfig(List) from a provider's parseLoadBalancingPolicyConfig() implementation.

Alternatively, the balancer may switch to a policy prior to handling resolved addresses for the first time. This causes graceful switch to ignore the service config and pass through the resolved addresses directly to the child policy.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static final class	GracefulSwitchLoadBalancer.Config

Nested classes/interfaces inherited from class io.grpc.LoadBalancer

LoadBalancer.CreateSubchannelArgs, LoadBalancer.ErrorPicker, LoadBalancer.Factory, LoadBalancer.FixedResultPicker, LoadBalancer.Helper, LoadBalancer.PickDetailsConsumer, LoadBalancer.PickResult, LoadBalancer.PickSubchannelArgs, LoadBalancer.ResolvedAddresses, LoadBalancer.Subchannel, LoadBalancer.SubchannelPicker, LoadBalancer.SubchannelStateListener

Field Summary

Fields

Modifier and Type	Field	Description
(package private) static final LoadBalancer.SubchannelPicker	BUFFER_PICKER
private LoadBalancer.Factory	currentBalancerFactory
private LoadBalancer	currentLb
private boolean	currentLbIsReady
private final LoadBalancer	defaultBalancer
private final LoadBalancer.Helper	helper
private LoadBalancer.Factory	pendingBalancerFactory
private LoadBalancer	pendingLb
private LoadBalancer.SubchannelPicker	pendingPicker
private ConnectivityState	pendingState
private boolean	switchToCalled

Fields inherited from class io.grpc.LoadBalancer

ATTR_HEALTH_CHECKING_CONFIG, DISABLE_SUBCHANNEL_RECONNECT_KEY, EMPTY_PICKER, HAS_HEALTH_PRODUCER_LISTENER_KEY, HEALTH_CONSUMER_LISTENER_ARG_KEY, IS_PETIOLE_POLICY

Constructor Summary

Constructors

Constructor	Description
GracefulSwitchLoadBalancer(LoadBalancer.Helper helper)

Method Summary

Modifier and Type	Method	Description
Status	acceptResolvedAddresses(LoadBalancer.ResolvedAddresses resolvedAddresses)	Accepts newly resolved addresses from the name resolution system.
static Object	createLoadBalancingPolicyConfig(LoadBalancer.Factory childFactory, Object childConfig)	Directly create a config to pass to GracefulSwitch.
protected LoadBalancer	delegate()	Returns the underlying balancer.
String	delegateType()
void	handleResolvedAddresses(LoadBalancer.ResolvedAddresses resolvedAddresses)	Handles newly resolved server groups and metadata attributes from name resolution system.
void	handleSubchannelState(LoadBalancer.Subchannel subchannel, ConnectivityStateInfo stateInfo)	Deprecated.
static NameResolver.ConfigOrError	parseLoadBalancingPolicyConfig(List<Map<String,?>> loadBalancingConfigs)	Provided a JSON list of LoadBalancingConfigs, parse it into a config to pass to GracefulSwitch.
static NameResolver.ConfigOrError	parseLoadBalancingPolicyConfig(List<Map<String,?>> loadBalancingConfigs, LoadBalancerRegistry lbRegistry)	Provided a JSON list of LoadBalancingConfigs, parse it into a config to pass to GracefulSwitch.
void	shutdown()	The channel asks the load-balancer to shutdown.
private void	swap()
void	switchTo(LoadBalancer.Factory newBalancerFactory)	Deprecated. Use parseLoadBalancingPolicyConfig() and pass the configuration to LoadBalancer.ResolvedAddresses.Builder.setLoadBalancingPolicyConfig(java.lang.Object)
private void	switchToInternal(LoadBalancer.Factory newBalancerFactory)

Methods inherited from class io.grpc.util.ForwardingLoadBalancer

canHandleEmptyAddressListFromNameResolution, handleNameResolutionError, requestConnection, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

defaultBalancer

private final LoadBalancer defaultBalancer

BUFFER_PICKER

static final LoadBalancer.SubchannelPicker BUFFER_PICKER

helper

private final LoadBalancer.Helper helper

currentBalancerFactory

@Nullable
private LoadBalancer.Factory currentBalancerFactory

currentLb

private LoadBalancer currentLb

pendingBalancerFactory

@Nullable
private LoadBalancer.Factory pendingBalancerFactory

pendingLb

private LoadBalancer pendingLb

pendingState

private ConnectivityState pendingState

pendingPicker

private LoadBalancer.SubchannelPicker pendingPicker

switchToCalled

private boolean switchToCalled

currentLbIsReady

private boolean currentLbIsReady

Constructor Details

GracefulSwitchLoadBalancer

public GracefulSwitchLoadBalancer(LoadBalancer.Helper helper)

Method Details

handleResolvedAddresses

public void handleResolvedAddresses(LoadBalancer.ResolvedAddresses resolvedAddresses)

Description copied from class: LoadBalancer

Handles newly resolved server groups and metadata attributes from name resolution system. servers contained in EquivalentAddressGroup should be considered equivalent but may be flattened into a single list if needed.

Implementations should not modify the given servers.

Overrides:

handleResolvedAddresses in class ForwardingLoadBalancer

Parameters:

resolvedAddresses - the resolved server addresses, attributes, and config.

acceptResolvedAddresses

public Status acceptResolvedAddresses(LoadBalancer.ResolvedAddresses resolvedAddresses)

Description copied from class: LoadBalancer

Accepts newly resolved addresses from the name resolution system. The EquivalentAddressGroup addresses should be considered equivalent but may be flattened into a single list if needed.

Implementations can choose to reject the given addresses by returning false.

Implementations should not modify the given addresses.

Overrides:

acceptResolvedAddresses in class LoadBalancer

Parameters:

resolvedAddresses - the resolved server addresses, attributes, and config.

Returns:

true if the resolved addresses were accepted. false if rejected.

switchTo

@Deprecated
public void switchTo(LoadBalancer.Factory newBalancerFactory)

Deprecated.

Use parseLoadBalancingPolicyConfig() and pass the configuration to LoadBalancer.ResolvedAddresses.Builder.setLoadBalancingPolicyConfig(java.lang.Object)

Gracefully switch to a new policy defined by the given factory, if the given factory isn't equal to the current one.

switchToInternal

private void switchToInternal(LoadBalancer.Factory newBalancerFactory)

swap

private void swap()

delegate

protected LoadBalancer delegate()

Description copied from class: ForwardingLoadBalancer

Returns the underlying balancer.

Specified by:

delegate in class ForwardingLoadBalancer

handleSubchannelState

@Deprecated
public void handleSubchannelState(LoadBalancer.Subchannel subchannel,
 ConnectivityStateInfo stateInfo)

Deprecated.

Description copied from class: LoadBalancer

Handles a state change on a Subchannel.

The initial state of a Subchannel is IDLE. You won't get a notification for the initial IDLE state.

If the new state is not SHUTDOWN, this method should create a new picker and call Helper.updateBalancingState(). Failing to do so may result in unnecessary delays of RPCs. Please refer to PickResult.withSubchannel()'s javadoc for more information.

SHUTDOWN can only happen in two cases. One is that LoadBalancer called LoadBalancer.Subchannel.shutdown() earlier, thus it should have already discarded this Subchannel. The other is that Channel is doing a forced shutdown or has already terminated, thus there won't be further requests to LoadBalancer. Therefore, the LoadBalancer usually don't need to react to a SHUTDOWN state.

Overrides:

handleSubchannelState in class ForwardingLoadBalancer

Parameters:

subchannel - the involved Subchannel

stateInfo - the new state

shutdown

public void shutdown()

Description copied from class: LoadBalancer

The channel asks the load-balancer to shutdown. No more methods on this class will be called after this method. The implementation should shutdown all Subchannels and OOB channels, and do any other cleanup as necessary.

Overrides:

shutdown in class ForwardingLoadBalancer

delegateType

public String delegateType()

parseLoadBalancingPolicyConfig

public static NameResolver.ConfigOrError parseLoadBalancingPolicyConfig(List<Map<String,?>> loadBalancingConfigs)

Provided a JSON list of LoadBalancingConfigs, parse it into a config to pass to GracefulSwitch.

parseLoadBalancingPolicyConfig

public static NameResolver.ConfigOrError parseLoadBalancingPolicyConfig(List<Map<String,?>> loadBalancingConfigs,
 LoadBalancerRegistry lbRegistry)

Provided a JSON list of LoadBalancingConfigs, parse it into a config to pass to GracefulSwitch.

createLoadBalancingPolicyConfig

public static Object createLoadBalancingPolicyConfig(LoadBalancer.Factory childFactory,
 @Nullable
 Object childConfig)

Directly create a config to pass to GracefulSwitch. The object returned is the same as would be found in ConfigOrError.getConfig().