Package io.grpc.util

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

    • Constructor Detail

      • GracefulSwitchLoadBalancer

        public GracefulSwitchLoadBalancer​(LoadBalancer.Helper helper)

    • Method Detail

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

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

      • 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().