Package io.grpc.xds

Class RingHashLoadBalancer

java.lang.Object
io.grpc.LoadBalancer
io.grpc.util.MultiChildLoadBalancer
io.grpc.xds.RingHashLoadBalancer
final class RingHashLoadBalancer extends io.grpc.util.MultiChildLoadBalancer
A LoadBalancer that provides consistent hashing based load balancing to upstream hosts. It implements the "Ketama" hashing that maps hosts onto a circle (the "ring") by hashing its addresses. Each request is routed to a host by hashing some property of the request and finding the nearest corresponding host clockwise around the ring. Each host is placed on the ring some number of times proportional to its weight. With the ring partitioned appropriately, the addition or removal of one host from a set of N hosts will affect only 1/N requests.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
    RingHashLoadBalancer.RingEntry
     
    (package private) static final class 
    RingHashLoadBalancer.RingHashConfig
    Configures the ring property.
    private static final class 
    RingHashLoadBalancer.RingHashPicker
     
    private static final class 
    RingHashLoadBalancer.SubchannelView
    An unmodifiable view of a subchannel with state not subject to its real connectivity state changes.

    Nested classes/interfaces inherited from class io.grpc.util.MultiChildLoadBalancer

    io.grpc.util.MultiChildLoadBalancer.AcceptResolvedAddrRetVal, io.grpc.util.MultiChildLoadBalancer.ChildLbState, io.grpc.util.MultiChildLoadBalancer.Endpoint

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

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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final XxHash64
    hashFunc
     
    private final io.grpc.LoadBalancer.Factory
    lazyLbFactory
     
    private final XdsLogger
    logger
     
    private List<RingHashLoadBalancer.RingEntry>
    ring
     
    private static final io.grpc.Status
    RPC_HASH_NOT_FOUND
     
    private final io.grpc.SynchronizationContext
    syncContext
     

    Fields inherited from class io.grpc.util.MultiChildLoadBalancer

    currentConnectivityState, pickFirstLbProvider, resolvingAddresses

    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
    RingHashLoadBalancer(io.grpc.LoadBalancer.Helper helper)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    io.grpc.Status
    acceptResolvedAddresses(io.grpc.LoadBalancer.ResolvedAddresses resolvedAddresses)
     
    private static List<RingHashLoadBalancer.RingEntry>
    buildRing(Map<io.grpc.EquivalentAddressGroup,Long> serverWeights, long totalWeight, double scale)
     
    protected io.grpc.util.MultiChildLoadBalancer.ChildLbState
    createChildLbState(Object key)
     
    static io.grpc.EquivalentAddressGroup
    stripAttrs(io.grpc.EquivalentAddressGroup eag)
     
    protected void
    updateOverallBalancingState()
    Updates the overall balancing state by aggregating the connectivity states of all subchannels.
    private io.grpc.Status
    validateAddrList(List<io.grpc.EquivalentAddressGroup> addrList)
     
    private String
    validateNoDuplicateAddresses(List<io.grpc.EquivalentAddressGroup> addrList)
     

    Methods inherited from class io.grpc.util.MultiChildLoadBalancer

    acceptResolvedAddressesInternal, aggregateState, createChildAddressesMap, getChildLbState, getChildLbStateEag, getChildLbStates, getHelper, getReadyChildren, handleNameResolutionError, shutdown, shutdownRemoved

    Methods inherited from class io.grpc.LoadBalancer

    canHandleEmptyAddressListFromNameResolution, handleResolvedAddresses, handleSubchannelState, requestConnection

    Methods inherited from class java.lang.Object

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

  • Field Details

    • RPC_HASH_NOT_FOUND

      private static final io.grpc.Status RPC_HASH_NOT_FOUND

    • hashFunc

      private static final XxHash64 hashFunc

    • lazyLbFactory

      private final io.grpc.LoadBalancer.Factory lazyLbFactory

    • logger

      private final XdsLogger logger

    • syncContext

      private final io.grpc.SynchronizationContext syncContext

    • ring

      private List<RingHashLoadBalancer.RingEntry> ring

  • Constructor Details

    • RingHashLoadBalancer

      RingHashLoadBalancer(io.grpc.LoadBalancer.Helper helper)

  • Method Details

    • acceptResolvedAddresses

      public io.grpc.Status acceptResolvedAddresses(io.grpc.LoadBalancer.ResolvedAddresses resolvedAddresses)
      Overrides:
      acceptResolvedAddresses in class io.grpc.util.MultiChildLoadBalancer

    • updateOverallBalancingState

      protected void updateOverallBalancingState()
      Updates the overall balancing state by aggregating the connectivity states of all subchannels.

      Aggregation rules (in order of dominance):

      1. If there is at least one subchannel in READY state, overall state is READY
      2. If there are 2 or more subchannels in TRANSIENT_FAILURE, overall state is TRANSIENT_FAILURE (to allow timely failover to another policy)
      3. If there is at least one subchannel in CONNECTING state, overall state is CONNECTING
      4. If there is one subchannel in TRANSIENT_FAILURE state and there is more than one subchannel, report CONNECTING
      5. If there is at least one subchannel in IDLE state, overall state is IDLE
      6. Otherwise, overall state is TRANSIENT_FAILURE
      Specified by:
      updateOverallBalancingState in class io.grpc.util.MultiChildLoadBalancer

    • createChildLbState

      protected io.grpc.util.MultiChildLoadBalancer.ChildLbState createChildLbState(Object key)
      Overrides:
      createChildLbState in class io.grpc.util.MultiChildLoadBalancer

    • validateAddrList

      private io.grpc.Status validateAddrList(List<io.grpc.EquivalentAddressGroup> addrList)

    • validateNoDuplicateAddresses

      @Nullable private String validateNoDuplicateAddresses(List<io.grpc.EquivalentAddressGroup> addrList)

    • buildRing

      private static List<RingHashLoadBalancer.RingEntry> buildRing(Map<io.grpc.EquivalentAddressGroup,Long> serverWeights, long totalWeight, double scale)

    • stripAttrs

      public static io.grpc.EquivalentAddressGroup stripAttrs(io.grpc.EquivalentAddressGroup eag)