io.grpc

Class LoadBalancer.Helper

java.lang.Object

io.grpc.LoadBalancer.Helper

Direct Known Subclasses:

ForwardingLoadBalancerHelper

Enclosing class:

LoadBalancer

@ThreadSafe
 @ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/1771")
public abstract static class LoadBalancer.Helper
extends Object

Provides essentials for LoadBalancer implementations.

Since:

1.2.0

Constructor Summary

Constructors

Constructor and Description
Helper()

Method Summary

Modifier and Type	Method and Description
abstract ManagedChannel	createOobChannel(EquivalentAddressGroup eag, String authority) Out-of-band channel for LoadBalancer’s own RPC needs, e.g., talking to an external load-balancer service.
LoadBalancer.Subchannel	createSubchannel(EquivalentAddressGroup addrs, Attributes attrs) Equivalent to createSubchannel(List, Attributes) with the given single EquivalentAddressGroup.
LoadBalancer.Subchannel	createSubchannel(List<EquivalentAddressGroup> addrs, Attributes attrs) Creates a Subchannel, which is a logical connection to the given group of addresses which are considered equivalent.
abstract String	getAuthority() Returns the authority string of the channel, which is derived from the DNS-style target name.
ChannelLogger	getChannelLogger() Returns the ChannelLogger for the Channel served by this LoadBalancer.
abstract NameResolver.Factory	getNameResolverFactory() Returns the NameResolver of the channel.
ScheduledExecutorService	getScheduledExecutorService() Returns a ScheduledExecutorService for scheduling delayed tasks.
SynchronizationContext	getSynchronizationContext() Returns a SynchronizationContext that runs tasks in the same Synchronization Context as that the callback methods on the LoadBalancer interface are run in.
void	runSerialized(Runnable task) Deprecated. use/implement getSynchronizationContext() instead
abstract void	updateBalancingState(ConnectivityState newState, LoadBalancer.SubchannelPicker newPicker) Set a new state with a new picker to the channel.
void	updateOobChannelAddresses(ManagedChannel channel, EquivalentAddressGroup eag) Updates the addresses used for connections in the Channel.
void	updateSubchannelAddresses(LoadBalancer.Subchannel subchannel, EquivalentAddressGroup addrs) Equivalent to updateSubchannelAddresses(io.grpc.LoadBalancer.Subchannel, List) with the given single EquivalentAddressGroup.
void	updateSubchannelAddresses(LoadBalancer.Subchannel subchannel, List<EquivalentAddressGroup> addrs) Replaces the existing addresses used with subchannel.

Methods inherited from class java.lang.Object

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

Constructor Detail

Helper

public Helper()

Method Detail

createSubchannel

public final LoadBalancer.Subchannel createSubchannel(EquivalentAddressGroup addrs,
                                                      Attributes attrs)

Equivalent to createSubchannel(List, Attributes) with the given single EquivalentAddressGroup.

Since:

1.2.0

createSubchannel

public LoadBalancer.Subchannel createSubchannel(List<EquivalentAddressGroup> addrs,
                                                Attributes attrs)

Creates a Subchannel, which is a logical connection to the given group of addresses which are considered equivalent. The attrs are custom attributes associated with this Subchannel, and can be accessed later through Subchannel.getAttributes().

It is recommended you call this method from the Synchronization Context, otherwise your logic around the creation may race with LoadBalancer.handleSubchannelState(io.grpc.LoadBalancer.Subchannel, io.grpc.ConnectivityStateInfo). See #5015 for more discussions.

The LoadBalancer is responsible for closing unused Subchannels, and closing all Subchannels within LoadBalancer.shutdown().

Throws:

IllegalArgumentException - if addrs is empty

Since:

1.14.0

updateSubchannelAddresses

public final void updateSubchannelAddresses(LoadBalancer.Subchannel subchannel,
                                            EquivalentAddressGroup addrs)

Equivalent to updateSubchannelAddresses(io.grpc.LoadBalancer.Subchannel, List) with the given single EquivalentAddressGroup.

Since:

1.4.0

updateSubchannelAddresses

public void updateSubchannelAddresses(LoadBalancer.Subchannel subchannel,
                                      List<EquivalentAddressGroup> addrs)

Replaces the existing addresses used with subchannel. This method is superior to createSubchannel(io.grpc.EquivalentAddressGroup, io.grpc.Attributes) when the new and old addresses overlap, since the subchannel can continue using an existing connection.

Throws:

IllegalArgumentException - if subchannel was not returned from createSubchannel(io.grpc.EquivalentAddressGroup, io.grpc.Attributes) or addrs is empty

Since:

1.14.0

createOobChannel

public abstract ManagedChannel createOobChannel(EquivalentAddressGroup eag,
                                                String authority)

Out-of-band channel for LoadBalancer’s own RPC needs, e.g., talking to an external load-balancer service.

The LoadBalancer is responsible for closing unused OOB channels, and closing all OOB channels within LoadBalancer.shutdown().

Since:

1.4.0

updateOobChannelAddresses

public void updateOobChannelAddresses(ManagedChannel channel,
                                      EquivalentAddressGroup eag)

Updates the addresses used for connections in the Channel. This is supperior to createOobChannel(io.grpc.EquivalentAddressGroup, java.lang.String) when the old and new addresses overlap, since the channel can continue using an existing connection.

Throws:

IllegalArgumentException - if channel was not returned from createOobChannel(io.grpc.EquivalentAddressGroup, java.lang.String)

Since:

1.4.0

updateBalancingState

public abstract void updateBalancingState(@Nonnull
                                          ConnectivityState newState,
                                          @Nonnull
                                          LoadBalancer.SubchannelPicker newPicker)

Set a new state with a new picker to the channel.

When a new picker is provided via updateBalancingState(), the channel will apply the picker on all buffered RPCs, by calling LoadBalancer.SubchannelPicker.pickSubchannel( LoadBalancer.PickSubchannelArgs).

The channel will hold the picker and use it for all RPCs, until updateBalancingState() is called again and a new picker replaces the old one. If updateBalancingState() has never been called, the channel will buffer all RPCs until a picker is provided.

The passed state will be the channel's new state. The SHUTDOWN state should not be passed and its behavior is undefined.

Since:

1.6.0

runSerialized

@Deprecated
public void runSerialized(Runnable task)

Deprecated. use/implement getSynchronizationContext() instead

Schedule a task to be run in the Synchronization Context, which serializes the task with the callback methods on the LoadBalancer interface.

Since:

1.2.0

getSynchronizationContext

public SynchronizationContext getSynchronizationContext()

Returns a SynchronizationContext that runs tasks in the same Synchronization Context as that the callback methods on the LoadBalancer interface are run in.

Pro-tip: in order to call SynchronizationContext.schedule(java.lang.Runnable, long, java.util.concurrent.TimeUnit, java.util.concurrent.ScheduledExecutorService), you need to provide a ScheduledExecutorService. getScheduledExecutorService() is provided for your convenience.

Since:

1.17.0

getScheduledExecutorService

public ScheduledExecutorService getScheduledExecutorService()

Returns a ScheduledExecutorService for scheduling delayed tasks.

This service is a shared resource and is only meant for quick tasks. DO NOT block or run time-consuming tasks.

The returned service doesn't support shutdown() and shutdownNow(). They will throw if called.

Since:

1.17.0

getNameResolverFactory

public abstract NameResolver.Factory getNameResolverFactory()

Returns the NameResolver of the channel.

Since:

1.2.0

getAuthority

public abstract String getAuthority()

Returns the authority string of the channel, which is derived from the DNS-style target name.

Since:

1.2.0

getChannelLogger

public ChannelLogger getChannelLogger()

Returns the ChannelLogger for the Channel served by this LoadBalancer.

Since:

1.17.0