io.grpc

Class LoadBalancer.Subchannel

java.lang.Object

io.grpc.LoadBalancer.Subchannel

Enclosing class:

LoadBalancer

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

A logical connection to a server, or a group of equivalent servers represented by an EquivalentAddressGroup.

It maintains at most one physical connection (aka transport) for sending new RPCs, while also keeps track of previous transports that has been shut down but not terminated yet.

If there isn't an active transport yet, and an RPC is assigned to the Subchannel, it will create a new transport. It won't actively create transports otherwise. requestConnection() can be used to ask Subchannel to create a transport if there isn't any.

Since:

1.2.0

Constructor Summary

Constructors

Constructor and Description
Subchannel()

Method Summary

Modifier and Type	Method and Description
Channel	asChannel() (Internal use only) returns a Channel that is backed by this Subchannel.
EquivalentAddressGroup	getAddresses() Returns the addresses that this Subchannel is bound to.
List<EquivalentAddressGroup>	getAllAddresses() Returns the addresses that this Subchannel is bound to.
abstract Attributes	getAttributes() The same attributes passed to Helper.createSubchannel().
ChannelLogger	getChannelLogger() Returns a ChannelLogger for this Subchannel.
abstract void	requestConnection() Asks the Subchannel to create a connection (aka transport), if there isn't an active one.
abstract void	shutdown() Shuts down the Subchannel.

Methods inherited from class java.lang.Object

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

Constructor Detail

Subchannel

public Subchannel()

Method Detail

shutdown

public abstract void shutdown()

Shuts down the Subchannel. After this method is called, this Subchannel should no longer be returned by the latest picker, and can be safely discarded.

It should be called from the Synchronization Context. Currently will log a warning if violated. It will become an exception eventually. See #5015 for the background.

Since:

1.2.0

requestConnection

public abstract void requestConnection()

Asks the Subchannel to create a connection (aka transport), if there isn't an active one.

It should be called from the Synchronization Context. See #5015 for the background.

Since:

1.2.0

getAddresses

public final EquivalentAddressGroup getAddresses()

Returns the addresses that this Subchannel is bound to. This can be called only if the Subchannel has only one EquivalentAddressGroup. Under the hood it calls getAllAddresses().

It should be called from the Synchronization Context. Currently will log a warning if violated. It will become an exception eventually. See #5015 for the background.

Throws:

IllegalStateException - if this subchannel has more than one EquivalentAddressGroup. Use getAllAddresses() instead

Since:

1.2.0

getAllAddresses

public List<EquivalentAddressGroup> getAllAddresses()

Returns the addresses that this Subchannel is bound to. The returned list will not be empty.

It should be called from the Synchronization Context. Currently will log a warning if violated. It will become an exception eventually. See #5015 for the background.

Since:

1.14.0

getAttributes

public abstract Attributes getAttributes()

The same attributes passed to Helper.createSubchannel(). LoadBalancer can use it to attach additional information here, e.g., the shard this Subchannel belongs to.

Since:

1.2.0

asChannel

@Internal
public Channel asChannel()

(Internal use only) returns a Channel that is backed by this Subchannel. This allows a LoadBalancer to issue its own RPCs for auxiliary purposes, such as health-checking, on already-established connections. This channel has certain restrictions:

1. It can issue RPCs only if the Subchannel is READY. If Channel.newCall(io.grpc.MethodDescriptor<RequestT, ResponseT>, io.grpc.CallOptions) is called when the Subchannel is not READY, the RPC will fail immediately.
2. It doesn't support wait-for-ready RPCs. Such RPCs will fail immediately.

RPCs made on this Channel is not counted when determining ManagedChannel's idle mode. In other words, they won't prevent ManagedChannel from entering idle mode.

Warning: RPCs made on this channel will prevent a shut-down transport from terminating. If you make long-running RPCs, you need to make sure they will finish in time after the Subchannel has transitioned away from READY state (notified through LoadBalancer.handleSubchannelState(io.grpc.LoadBalancer.Subchannel, io.grpc.ConnectivityStateInfo)).

Warning: this is INTERNAL API, is not supposed to be used by external users, and may change without notice. If you think you must use it, please file an issue.

getChannelLogger

public ChannelLogger getChannelLogger()

Returns a ChannelLogger for this Subchannel.

Since:

1.17.0