@ExperimentalApi(value="https://github.com/grpc/grpc-java/issues/1771") public abstract static class LoadBalancer.Subchannel extends Object
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.
start(io.grpc.LoadBalancer.SubchannelStateListener)
must be called prior to calling any other methods, with the exception of
shutdown()
, which can be called at any time.
Constructor and Description |
---|
Subchannel() |
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. |
Object |
getInternalSubchannel()
(Internal use only) returns an object that represents the underlying subchannel that is used
by the Channel for sending RPCs when this
LoadBalancer.Subchannel is picked. |
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.
|
void |
start(LoadBalancer.SubchannelStateListener listener)
Starts the Subchannel.
|
void |
updateAddresses(List<EquivalentAddressGroup> addrs)
Replaces the existing addresses used with this
Subchannel . |
public void start(LoadBalancer.SubchannelStateListener listener)
Must be called prior to any other method on this class, except for shutdown()
which
may be called at any time.
Must be called from the Synchronization Context
,
otherwise it may throw. See
#5015 for more discussions.
listener
- receives state updates for this Subchannel.public abstract void shutdown()
picker
, and can be safely discarded.
Calling it on an already shut-down Subchannel has no effect.
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.
public abstract void requestConnection()
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.
public final EquivalentAddressGroup getAddresses()
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.
IllegalStateException
- if this subchannel has more than one EquivalentAddressGroup.
Use getAllAddresses()
insteadpublic List<EquivalentAddressGroup> 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.
public abstract Attributes getAttributes()
Helper.createSubchannel()
.
LoadBalancer can use it to attach additional information here, e.g., the shard this
Subchannel belongs to.@Internal public Channel asChannel()
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:
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.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.
public ChannelLogger getChannelLogger()
ChannelLogger
for this Subchannel.public void updateAddresses(List<EquivalentAddressGroup> addrs)
Subchannel
. If the new and old
addresses overlap, the Subchannel can continue using an existing connection.
It must be called from the Synchronization Context or will throw.
IllegalArgumentException
- if addrs
is empty@Internal public Object getInternalSubchannel()
LoadBalancer.Subchannel
is picked. This is an opaque
object that is both provided and consumed by the Channel. Its type is not
Subchannel
.
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 and we can consider removing its "internal" status.