Involved Source Files Package balancer defines APIs for load balancing in gRPC.
All APIs in this package are experimental.conn_state_evaluator.gosubconn.go
Package-Level Type Names (total 18, all are exported)
/* sort exporteds by: | */
Balancer takes input from gRPC, manages SubConns, and collects and aggregates
the connectivity states.
It also generates and updates the Picker used by gRPC to pick SubConns for RPCs.
UpdateClientConnState, ResolverError, UpdateSubConnState, and Close are
guaranteed to be called synchronously from the same goroutine. There's no
guarantee on picker.Pick, it may be called anytime. Close closes the balancer. The balancer is not currently required to
call SubConn.Shutdown for its existing SubConns; however, this will be
required in a future release, so it is recommended. ExitIdle instructs the LB policy to reconnect to backends / exit the
IDLE state, if appropriate and possible. Note that SubConns that enter
the IDLE state will not reconnect until SubConn.Connect is called. ResolverError is called by gRPC when the name resolver reports an error. UpdateClientConnState is called by gRPC when the state of the ClientConn
changes. If the error returned is ErrBadResolverState, the ClientConn
will begin calling ResolveNow on the active name resolver with
exponential backoff until a subsequent call to UpdateClientConnState
returns a nil error. Any other errors are currently ignored. UpdateSubConnState is called by gRPC when the state of a SubConn
changes.
Deprecated: Use NewSubConnOptions.StateListener when creating the
SubConn instead.
*google.golang.org/grpc/internal/balancer/gracefulswitch.Balancer
*google.golang.org/grpc/balancer/base.baseBalancer
*google.golang.org/grpc/balancer/endpointsharding.endpointSharding
*google.golang.org/grpc/balancer/pickfirst.pickfirstBalancer
*google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.pickfirstBalancer
*google.golang.org/grpc/balancer/roundrobin.rrBalancer
*google.golang.org/grpc/internal/balancer/gracefulswitch.balancerWrapper
Balancer : ExitIdler
Balancer : google.golang.org/grpc/balancer/endpointsharding.ExitIdler
func Builder.Build(cc ClientConn, opts BuildOptions) Balancer
func google.golang.org/grpc/balancer/endpointsharding.NewBalancer(cc ClientConn, opts BuildOptions, childBuilder endpointsharding.ChildBuilderFunc, esOpts endpointsharding.Options) Balancer
Builder creates a balancer. Build creates a new balancer with the ClientConn. Name returns the name of balancers built by this builder.
It will be used to pick balancers (for example in service config).
*google.golang.org/grpc/balancer/base.baseBuilder
google.golang.org/grpc/balancer/pickfirst.pickfirstBuilder
google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.pickfirstBuilder
google.golang.org/grpc/balancer/roundrobin.builder
func Get(name string) Builder
func google.golang.org/grpc/balancer/base.NewBalancerBuilder(name string, pb base.PickerBuilder, config base.Config) Builder
func Register(b Builder)
func google.golang.org/grpc/internal/balancer/gracefulswitch.(*Balancer).SwitchTo(builder Builder) error
func google.golang.org/grpc/internal/balancer/gracefulswitch.(*Balancer).switchTo(builder Builder) (*gracefulswitch.balancerWrapper, error)
BuildOptions contains additional information for Build. Authority is the server name to use as part of the authentication
handshake when communicating with a remote load balancer server. Balancer
implementations which do not communicate with a remote load balancer
server can ignore this field. ChannelzParent is the parent ClientConn's channelz channel. CredsBundle is the credentials bundle to use when communicating with a
remote load balancer server. Balancer implementations which do not
communicate with a remote load balancer server can ignore this field. CustomUserAgent is the custom user agent set on the parent ClientConn.
The balancer should set the same custom user agent if it creates a
ClientConn. DialCreds is the transport credentials to use when communicating with a
remote load balancer server. Balancer implementations which do not
communicate with a remote load balancer server can ignore this field. Dialer is the custom dialer to use when communicating with a remote load
balancer server. Balancer implementations which do not communicate with a
remote load balancer server can ignore this field. Target contains the parsed address info of the dial target. It is the
same resolver.Target as passed to the resolver. See the documentation for
the resolver.Target type for details about what it contains.
func Builder.Build(cc ClientConn, opts BuildOptions) Balancer
func google.golang.org/grpc/balancer/endpointsharding.NewBalancer(cc ClientConn, opts BuildOptions, childBuilder endpointsharding.ChildBuilderFunc, esOpts endpointsharding.Options) Balancer
func google.golang.org/grpc/internal/balancer/gracefulswitch.NewBalancer(cc ClientConn, opts BuildOptions) *gracefulswitch.Balancer
ClientConn represents a gRPC ClientConn.
This interface is to be implemented by gRPC. Users should not need a
brand new implementation of this interface. For the situations like
testing, the new implementation should embed this interface. This allows
gRPC to add new methods to this interface.
NOTICE: This interface is intended to be implemented by gRPC, or intercepted
by custom load balancing polices. Users should not need their own complete
implementation of this interface -- they should always delegate to a
ClientConn passed to Builder.Build() by embedding it in their
implementations. An embedded ClientConn must never be nil, or runtime panics
will occur. MetricsRecorder provides the metrics recorder that balancers can use to
record metrics. Balancer implementations which do not register metrics on
metrics registry and record on them can ignore this method. The returned
MetricsRecorder is guaranteed to never be nil. NewSubConn is called by balancer to create a new SubConn.
It doesn't block and wait for the connections to be established.
Behaviors of the SubConn can be controlled by options.
Deprecated: please be aware that in a future version, SubConns will only
support one address per SubConn. RemoveSubConn removes the SubConn from ClientConn.
The SubConn will be shutdown.
Deprecated: use SubConn.Shutdown instead. ResolveNow is called by balancer to notify gRPC to do a name resolving. Target returns the dial target for this ClientConn.
Deprecated: Use the Target field in the BuildOptions instead. UpdateAddresses updates the addresses used in the passed in SubConn.
gRPC checks if the currently connected address is still in the new list.
If so, the connection will be kept. Else, the connection will be
gracefully closed, and a new connection will be created.
This may trigger a state transition for the SubConn.
Deprecated: this method will be removed. Create new SubConns for new
addresses instead. UpdateState notifies gRPC that the balancer's internal state has
changed.
gRPC will update the connectivity state of the ClientConn, and will call
Pick on the new Picker to pick new SubConns.( ClientConn) enforceClientConnEmbedding()
*google.golang.org/grpc/balancer/endpointsharding.balancerWrapper
*google.golang.org/grpc.ccBalancerWrapper
*google.golang.org/grpc/internal/balancer/gracefulswitch.balancerWrapper
ClientConn : google.golang.org/grpc/internal.EnforceClientConnEmbedding
func Builder.Build(cc ClientConn, opts BuildOptions) Balancer
func google.golang.org/grpc/balancer/endpointsharding.NewBalancer(cc ClientConn, opts BuildOptions, childBuilder endpointsharding.ChildBuilderFunc, esOpts endpointsharding.Options) Balancer
func google.golang.org/grpc/internal/balancer/gracefulswitch.NewBalancer(cc ClientConn, opts BuildOptions) *gracefulswitch.Balancer
ClientConnState describes the state of a ClientConn relevant to the
balancer. The parsed load balancing configuration returned by the builder's
ParseConfig method, if implemented.ResolverStateresolver.State
func Balancer.UpdateClientConnState(ClientConnState) error
func google.golang.org/grpc/internal/balancer/gracefulswitch.(*Balancer).UpdateClientConnState(state ClientConnState) error
ConfigParser parses load balancer configs. ParseConfig parses the JSON load balancer config provided into an
internal form or returns an error if the config is invalid. For future
compatibility reasons, unknown fields in the config should be ignored.
google.golang.org/grpc/balancer/pickfirst.pickfirstBuilder
google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.pickfirstBuilder
ConnectivityStateEvaluator takes the connectivity states of multiple SubConns
and returns one aggregated connectivity state.
It's not thread safe. // Number of addrConns in connecting state. // Number of addrConns in idle state. // Number of addrConns in ready state. // Number of addrConns in transient failure state. CurrentState returns the current aggregate conn state by evaluating the counters RecordTransition records state change happening in subConn and based on that
it evaluates what aggregated state should be.
- If at least one SubConn in Ready, the aggregated state is Ready;
- Else if at least one SubConn in Connecting, the aggregated state is Connecting;
- Else if at least one SubConn is Idle, the aggregated state is Idle;
- Else if at least one SubConn is TransientFailure (or there are no SubConns), the aggregated state is Transient Failure.
Shutdown is not considered.
DoneInfo contains additional information for done. BytesReceived indicates if any byte has been received from the server. BytesSent indicates if any bytes have been sent to the server. Err is the rpc error the RPC finished with. It could be nil. ServerLoad is the load received from server. It's usually sent as part of
trailing metadata.
The only supported type now is *orca_v3.LoadReport. Trailer contains the metadata from the RPC's trailer, if present.
ExitIdler is an optional interface for balancers to implement. If
implemented, ExitIdle will be called when ClientConn.Connect is called, if
the ClientConn is idle. If unimplemented, ClientConn.Connect will cause
all SubConns to connect.
Deprecated: All balancers must implement this interface. This interface will
be removed in a future release. ExitIdle instructs the LB policy to reconnect to backends / exit the
IDLE state, if appropriate and possible. Note that SubConns that enter
the IDLE state will not reconnect until SubConn.Connect is called.Balancer(interface)
google.golang.org/grpc/balancer/endpointsharding.ExitIdler(interface)
*google.golang.org/grpc/internal/balancer/gracefulswitch.Balancer
*google.golang.org/grpc/balancer/base.baseBalancer
*google.golang.org/grpc/balancer/endpointsharding.balancerWrapper
*google.golang.org/grpc/balancer/endpointsharding.endpointSharding
*google.golang.org/grpc/balancer/pickfirst.pickfirstBalancer
*google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.pickfirstBalancer
google.golang.org/grpc/balancer/roundrobin.rrBalancer
google.golang.org/grpc/internal/balancer/gracefulswitch.balancerWrapper
ExitIdler : google.golang.org/grpc/balancer/endpointsharding.ExitIdler
NewSubConnOptions contains options to create new SubConn. CredsBundle is the credentials bundle that will be used in the created
SubConn. If it's nil, the original creds from grpc DialOptions will be
used.
Deprecated: Use the Attributes field in resolver.Address to pass
arbitrary data to the credential handshaker. HealthCheckEnabled indicates whether health check service should be
enabled on this SubConn StateListener is called when the state of the subconn changes. If nil,
Balancer.UpdateSubConnState will be called instead. Will never be
invoked until after Connect() is called on the SubConn created with
these options.
func ClientConn.NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
func google.golang.org/grpc.(*ClientConn).newAddrConnLocked(addrs []resolver.Address, opts NewSubConnOptions) (*grpc.addrConn, error)
Picker is used by gRPC to pick a SubConn to send an RPC.
Balancer is expected to generate a new picker from its snapshot every time its
internal state has changed.
The pickers used by gRPC can be updated by ClientConn.UpdateState(). Pick returns the connection to use for this RPC and related information.
Pick should not block. If the balancer needs to do I/O or any blocking
or time-consuming work to service this call, it should return
ErrNoSubConnAvailable, and the Pick call will be repeated by gRPC when
the Picker is updated (using ClientConn.UpdateState).
If an error is returned:
- If the error is ErrNoSubConnAvailable, gRPC will block until a new
Picker is provided by the balancer (using ClientConn.UpdateState).
- If the error is a status error (implemented by the grpc/status
package), gRPC will terminate the RPC with the code and message
provided.
- For all other errors, wait for ready RPCs will wait, but non-wait for
ready RPCs will be terminated with this error's Error() string and
status code Unavailable.
*google.golang.org/grpc/balancer/base.errPicker
*google.golang.org/grpc/balancer/endpointsharding.pickerWithChildStates
*google.golang.org/grpc/balancer/pickfirst.idlePicker
*google.golang.org/grpc/balancer/pickfirst.picker
*google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.idlePicker
*google.golang.org/grpc/balancer/pickfirst/pickfirstleaf.picker
func google.golang.org/grpc/balancer/base.NewErrPicker(err error) Picker
func google.golang.org/grpc/balancer/base.PickerBuilder.Build(info base.PickerBuildInfo) Picker
func google.golang.org/grpc/balancer/endpointsharding.ChildStatesFromPicker(picker Picker) []endpointsharding.ChildState
PickInfo contains additional information for the Pick operation. Ctx is the RPC's context, and may contain relevant RPC-level information
like the outgoing header metadata. FullMethodName is the method name that NewClientStream() is called
with. The canonical format is /service/Method.
func Picker.Pick(info PickInfo) (PickResult, error)
PickResult contains information related to a connection chosen for an RPC. Done is called when the RPC is completed. If the SubConn is not ready,
this will be called with a nil parameter. If the SubConn is not a valid
type, Done may not be called. May be nil if the balancer does not wish
to be notified when the RPC completes. Metadata provides a way for LB policies to inject arbitrary per-call
metadata. Any metadata returned here will be merged with existing
metadata added by the client application.
LB policies with child policies are responsible for propagating metadata
injected by their children to the ClientConn, as part of Pick(). SubConn is the connection to use for this pick, if its state is Ready.
If the state is not Ready, gRPC will block the RPC until a new Picker is
provided by the balancer (using ClientConn.UpdateState). The SubConn
must be one returned by ClientConn.NewSubConn.
func Picker.Pick(info PickInfo) (PickResult, error)
func google.golang.org/grpc.doneChannelzWrapper(acbw *grpc.acBalancerWrapper, result *PickResult)
A Producer is a type shared among potentially many consumers. It is
associated with a SubConn, and an implementation will typically contain
other methods to provide additional functionality, e.g. configuration or
subscription registration.
func ProducerBuilder.Build(grpcClientConnInterface any) (p Producer, close func())
func SubConn.GetOrBuildProducer(ProducerBuilder) (p Producer, close func())
A ProducerBuilder is a simple constructor for a Producer. It is used by the
SubConn to create producers when needed. Build creates a Producer. The first parameter is always a
grpc.ClientConnInterface (a type to allow creating RPCs/streams on the
associated SubConn), but is declared as `any` to avoid a dependency
cycle. Build also returns a close function that will be called when all
references to the Producer have been given up for a SubConn, or when a
connectivity state change occurs on the SubConn. The close function
should always block until all asynchronous cleanup work is completed.
*google.golang.org/grpc/health.producerBuilder
func SubConn.GetOrBuildProducer(ProducerBuilder) (p Producer, close func())
State contains the balancer's state relevant to the gRPC ClientConn. State contains the connectivity state of the balancer, which is used to
determine the state of the ClientConn. Picker is used to choose connections (SubConns) for RPCs.
func ClientConn.UpdateState(State)
A SubConn represents a single connection to a gRPC backend service.
All SubConns start in IDLE, and will not try to connect. To trigger a
connection attempt, Balancers must call Connect.
If the connection attempt fails, the SubConn will transition to
TRANSIENT_FAILURE for a backoff period, and then return to IDLE. If the
connection attempt succeeds, it will transition to READY.
If a READY SubConn becomes disconnected, the SubConn will transition to IDLE.
If a connection re-enters IDLE, Balancers must call Connect again to trigger
a new connection attempt.
Each SubConn contains a list of addresses. gRPC will try to connect to the
addresses in sequence, and stop trying the remainder once the first
connection is successful. However, this behavior is deprecated. SubConns
should only use a single address.
NOTICE: This interface is intended to be implemented by gRPC, or intercepted
by custom load balancing polices. Users should not need their own complete
implementation of this interface -- they should always delegate to a SubConn
returned by ClientConn.NewSubConn() by embedding it in their implementations.
An embedded SubConn must never be nil, or runtime panics will occur. Connect starts the connecting for this SubConn. GetOrBuildProducer returns a reference to the existing Producer for this
ProducerBuilder in this SubConn, or, if one does not currently exist,
creates a new one and returns it. Returns a close function which may be
called when the Producer is no longer needed. Otherwise the producer
will automatically be closed upon connection loss or subchannel close.
Should only be called on a SubConn in state Ready. Otherwise the
producer will be unable to create streams. RegisterHealthListener registers a health listener that receives health
updates for a Ready SubConn. Only one health listener can be registered
at a time. A health listener should be registered each time the SubConn's
connectivity state changes to READY. Registering a health listener when
the connectivity state is not READY may result in undefined behaviour.
This method must not be called synchronously while handling an update
from a previously registered health listener. Shutdown shuts down the SubConn gracefully. Any started RPCs will be
allowed to complete. No future calls should be made on the SubConn.
One final state update will be delivered to the StateListener (or
UpdateSubConnState; deprecated) with ConnectivityState of Shutdown to
indicate the shutdown operation. This may be delivered before
in-progress RPCs are complete and the actual connection is closed. UpdateAddresses updates the addresses used in this SubConn.
gRPC checks if currently-connected address is still in the new list.
If it's in the list, the connection will be kept.
If it's not in the list, the connection will gracefully close, and
a new connection will be created.
This will trigger a state transition for the SubConn.
Deprecated: this method will be removed. Create new SubConns for new
addresses instead.( SubConn) enforceSubConnEmbedding()
*google.golang.org/grpc.acBalancerWrapper
SubConn : google.golang.org/grpc/internal.EnforceSubConnEmbedding
func ClientConn.NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
func Balancer.UpdateSubConnState(SubConn, SubConnState)
func ClientConn.RemoveSubConn(SubConn)
func ClientConn.UpdateAddresses(SubConn, []resolver.Address)
func google.golang.org/grpc/internal/balancer/gracefulswitch.(*Balancer).UpdateSubConnState(sc SubConn, state SubConnState)
func google.golang.org/grpc/health.registerClientSideHealthCheckListener(ctx context.Context, sc SubConn, serviceName string, listener func(SubConnState)) func()
func google.golang.org/grpc/internal/balancer/gracefulswitch.(*Balancer).updateSubConnState(sc SubConn, state SubConnState, cb func(SubConnState))
SubConnState describes the state of a SubConn. ConnectionError is set if the ConnectivityState is TransientFailure,
describing the reason the SubConn failed. Otherwise, it is nil. ConnectivityState is the connectivity state of the SubConn. connectedAddr contains the connected address when ConnectivityState is
Ready. Otherwise, it is indeterminate.
func Balancer.UpdateSubConnState(SubConn, SubConnState)
func google.golang.org/grpc/internal/balancer/gracefulswitch.(*Balancer).UpdateSubConnState(sc SubConn, state SubConnState)
func connectedAddress(scs SubConnState) resolver.Address
func setConnectedAddress(scs *SubConnState, addr resolver.Address)
func google.golang.org/grpc/internal/balancer/gracefulswitch.(*Balancer).updateSubConnState(sc SubConn, state SubConnState, cb func(SubConnState))
Package-Level Functions (total 7, in which 3 are exported)
Get returns the resolver builder registered with the given name.
Note that the compare is done in a case-insensitive fashion.
If no builder is register with the name, nil will be returned.
Register registers the balancer builder to the balancer map. b.Name
(lowercased) will be used as the name registered with this builder. If the
Builder implements ConfigParser, ParseConfig will be called when new service
configs are received by the resolver, and the result will be provided to the
Balancer in UpdateClientConnState.
NOTE: this function must only be called during initialization time (i.e. in
an init() function), and is not thread-safe. If multiple Balancers are
registered with the same name, the one registered last will take effect.
TransientFailureError returns e. It exists for backward compatibility and
will be deleted soon.
Deprecated: no longer necessary, picker errors are treated this way by
default.
connectedAddress returns the connected address for a SubConnState. The
address is only valid if the state is READY.
setConnectedAddress sets the connected address for a SubConnState.
unregisterForTesting deletes the balancer with the given name from the
balancer map.
This function is not thread-safe.
Package-Level Variables (total 5, in which 3 are exported)
ErrBadResolverState may be returned by UpdateClientConnState to indicate a
problem with the provided name resolver data.
ErrNoSubConnAvailable indicates no SubConn is available for pick().
gRPC will block the RPC until a new picker is available via UpdateState().
ErrTransientFailure indicates all SubConns are in TransientFailure.
WaitForReady RPCs will block, non-WaitForReady RPCs will fail.
Deprecated: return an appropriate error based on the last resolution or
connection attempt instead. The behavior is the same for any non-gRPC
status error.