func Register(bBuilder)

type Balancer interface {// 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.UpdateClientConnState(ClientConnState)error// ResolverError is called by gRPC when the name resolver reports an error.ResolverError(error)// UpdateSubConnState is called by gRPC when the state of a SubConn// changes.//// Deprecated: Use NewSubConnOptions.StateListener when creating the// SubConn instead.UpdateSubConnState(SubConn,SubConnState)// 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.Close()// 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.ExitIdle()}

type BuildOptions struct {// 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.DialCredscredentials.TransportCredentials// 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.CredsBundlecredentials.Bundle// 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.Dialer func(context.Context,string) (net.Conn,error)// 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.Authoritystring// ChannelzParent is the parent ClientConn's channelz channel.ChannelzParentchannelz.Identifier// 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.CustomUserAgentstring// 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.Targetresolver.Target}

type Builder interface {// Build creates a new balancer with the ClientConn.Build(ccClientConn, optsBuildOptions)Balancer// Name returns the name of balancers built by this builder.// It will be used to pick balancers (for example in service config).Name()string}

funcGet¶

func Get(namestring)Builder

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.

type ClientConn interface {// 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.NewSubConn([]resolver.Address,NewSubConnOptions) (SubConn,error)// RemoveSubConn removes the SubConn from ClientConn.// The SubConn will be shutdown.//// Deprecated: use SubConn.Shutdown instead.RemoveSubConn(SubConn)// 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.UpdateAddresses(SubConn, []resolver.Address)// 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.UpdateState(State)// ResolveNow is called by balancer to notify gRPC to do a name resolving.ResolveNow(resolver.ResolveNowOptions)// Target returns the dial target for this ClientConn.//// Deprecated: Use the Target field in the BuildOptions instead.Target()string// 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.MetricsRecorder()estats.MetricsRecorder// EnforceClientConnEmbedding is included to force implementers to embed// another implementation of this interface, allowing gRPC to add methods// without breaking users.internal.EnforceClientConnEmbedding}

type ClientConnState struct {ResolverStateresolver.State// The parsed load balancing configuration returned by the builder's// ParseConfig method, if implemented.BalancerConfigserviceconfig.LoadBalancingConfig}

type ConfigParser interface {// 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.ParseConfig(LoadBalancingConfigJSONjson.RawMessage) (serviceconfig.LoadBalancingConfig,error)}

type ConnectivityStateEvaluator struct {// contains filtered or unexported fields}

func (*ConnectivityStateEvaluator)CurrentState¶added inv1.51.0

func (cse *ConnectivityStateEvaluator) CurrentState()connectivity.State

CurrentState returns the current aggregate conn state by evaluating the counters

func (*ConnectivityStateEvaluator)RecordTransition¶added inv1.13.0

func (cse *ConnectivityStateEvaluator) RecordTransition(oldState, newStateconnectivity.State)connectivity.State

RecordTransition records state change happening in subConn and based on thatit 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.

type DoneInfo struct {// Err is the rpc error the RPC finished with. It could be nil.Errerror// Trailer contains the metadata from the RPC's trailer, if present.Trailermetadata.MD// BytesSent indicates if any bytes have been sent to the server.BytesSentbool// BytesReceived indicates if any byte has been received from the server.BytesReceivedbool// 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.ServerLoadany}

type NewSubConnOptions struct {// 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.CredsBundlecredentials.Bundle// HealthCheckEnabled indicates whether health check service should be// enabled on this SubConnHealthCheckEnabledbool// 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.StateListener func(SubConnState)}

type PickInfo struct {// FullMethodName is the method name that NewClientStream() is called// with. The canonical format is /service/Method.FullMethodNamestring// Ctx is the RPC's context, and may contain relevant RPC-level information// like the outgoing header metadata.Ctxcontext.Context}

type PickResult struct {// 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.SubConnSubConn// 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.Done func(DoneInfo)// 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().Metadatametadata.MD}

type Picker interface {// 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.Pick(infoPickInfo) (PickResult,error)}

type Producerany

type ProducerBuilder interface {// 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.Build(grpcClientConnInterfaceany) (pProducer, close func())}

type State struct {// State contains the connectivity state of the balancer, which is used to// determine the state of the ClientConn.ConnectivityStateconnectivity.State// Picker is used to choose connections (SubConns) for RPCs.PickerPicker}

type SubConn interface {// 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.UpdateAddresses([]resolver.Address)// Connect starts the connecting for this SubConn.Connect()// 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.GetOrBuildProducer(ProducerBuilder) (pProducer, close func())// 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.Shutdown()// 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.RegisterHealthListener(func(SubConnState))// EnforceSubConnEmbedding is included to force implementers to embed// another implementation of this interface, allowing gRPC to add methods// without breaking users.internal.EnforceSubConnEmbedding}

type SubConnState struct {// ConnectivityState is the connectivity state of the SubConn.ConnectivityStateconnectivity.State// ConnectionError is set if the ConnectivityState is TransientFailure,// describing the reason the SubConn failed.  Otherwise, it is nil.ConnectionErrorerror// contains filtered or unexported fields}