io.grpc

Class LoadBalancer2.PickResult

java.lang.Object

io.grpc.LoadBalancer2.PickResult

Enclosing class:

LoadBalancer2

@Immutable
public static final class LoadBalancer2.PickResult
extends Object

A balancing decision made by SubchannelPicker for an RPC.

The outcome of the decision will be one of the following:

• Proceed: if a Subchannel is provided via withSubchannel(), and is in READY state when the RPC tries to start on it, the RPC will proceed on that Subchannel.
• Error: if an error is provided via withError(), and the RPC is not wait-for-ready (i.e., CallOptions.withWaitForReady() was not called), the RPC will fail immediately with the given error.
• Buffer: in all other cases, the RPC will be buffered in the Channel, until the next picker is provided via Helper.updatePicker(), when the RPC will go through the same picking process again.

Method Summary

Modifier and Type	Method and Description
Status	getStatus() The status associated with this result.
LoadBalancer2.Subchannel	getSubchannel() The Subchannel if this result was created by withSubchannel(), or null otherwise.
String	toString()
static LoadBalancer2.PickResult	withError(Status error) A decision to report a connectivity error to the RPC.
static LoadBalancer2.PickResult	withNoResult() No decision could be made.
static LoadBalancer2.PickResult	withSubchannel(LoadBalancer2.Subchannel subchannel) A decision to proceed the RPC on a Subchannel.

Methods inherited from class java.lang.Object

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

Method Detail

withSubchannel

public static LoadBalancer2.PickResult withSubchannel(LoadBalancer2.Subchannel subchannel)

A decision to proceed the RPC on a Subchannel.

Only Subchannels returned by Helper.createSubchannel() will work. DO NOT try to use your own implementations of Subchannels, as they won't work.

When the RPC tries to use the return Subchannel, which is briefly after this method returns, the state of the Subchannel will decide where the RPC would go:

• READY: the RPC will proceed on this Subchannel.
• IDLE: the RPC will be buffered. Subchannel will attempt to create connection.
• All other states: the RPC will be buffered.

All buffered RPCs will stay buffered until the next call of Helper.updatePicker(), which will trigger a new picking process.

Note that Subchannel's state may change at the same time the picker is making the decision, which means the decision may be made with (to-be) outdated information. For example, a picker may return a Subchannel known to be READY, but it has become IDLE when is about to be used by the RPC, which makes the RPC to be buffered. The LoadBalancer will soon learn about the Subchannels' transition from READY to IDLE, create a new picker and allow the RPC to use another READY transport if there is any.

You will want to avoid running into a situation where there are READY Subchannels out there but some RPCs are still buffered for longer than a brief time.

• This can happen if you return Subchannels with states other than READY and IDLE. For example, suppose you round-robin on 2 Subchannels, in READY and CONNECTING states respectively. If the picker ignores the state and pick them equally, 50% of RPCs will be stuck in buffered state until both Subchannels are READY.
• This can also happen if you don't create a new picker at key state changes of Subchannels. Take the above round-robin example again. Suppose you do pick only READY and IDLE Subchannels, and initially both Subchannels are READY. Now one becomes IDLE, then CONNECTING and stays CONNECTING for a long time. If you don't create a new picker in response to the CONNECTING state to exclude that Subchannel, 50% of RPCs will hit it and be buffered even though the other Subchannel is READY.

In order to prevent unnecessary delay of RPCs, the rules of thumb are:

1. The picker should only pick Subchannels that are known as READY or IDLE. Whether to pick IDLE Subchannels depends on whether you want Subchannels to connect on-demand or actively:
   • If you want connect-on-demand, include IDLE Subchannels in your pick results, because when an RPC tries to use an IDLE Subchannel, the Subchannel will try to connect.
   • If you want Subchannels to be always connected even when there is no RPC, you would call Subchannel.requestConnection() whenever the Subchannel has transitioned to IDLE, then you don't need to include IDLE Subchannels in your pick results.
2. Always create a new picker and call Helper.updatePicker() whenever handleSubchannelState() is called, unless the new state is SHUTDOWN. See handleSubchannelState's javadoc for more details.

withError

public static LoadBalancer2.PickResult withError(Status error)

A decision to report a connectivity error to the RPC. If the RPC is wait-for-ready, it will stay buffered. Otherwise, it will fail with the given error.

Parameters:

error - the error status. Must not be OK.

withNoResult

public static LoadBalancer2.PickResult withNoResult()

No decision could be made. The RPC will stay buffered.

getSubchannel

@Nullable
public LoadBalancer2.Subchannel getSubchannel()

The Subchannel if this result was created by withSubchannel(), or null otherwise.

getStatus

public Status getStatus()

The status associated with this result. Non-OK if created with withError, or OK otherwise.

toString

public String toString()

Overrides:

toString in class Object