Package: google.golang.org/grpc/internal/balancer/gracefulswitch

package gracefulswitch Import Path google.golang.org/grpc/internal/balancer/gracefulswitch (on go.dev) Dependency Relation imports 9 packages, and imported by one package Involved Source Files config.go d gracefulswitch.go Package gracefulswitch implements a graceful switch load balancer. Package-Level Type Names (total 3, in which 1 is exported) /* sort exporteds by: alphabet | popularity */ type Balancer (struct) Balancer is a utility to gracefully switch from one balancer to a new balancer. It implements the balancer.Balancer interface. Fields (total 7, none are exported) /* 7 unexporteds ... *//* 7 unexporteds: */ bOpts balancer.BuildOptions balancerCurrent *balancerWrapper balancerPending *balancerWrapper cc balancer.ClientConn closed bool // set to true when this balancer is closed currentMu sync.Mutex currentMu must be locked before mu. This mutex guards against this sequence of events: UpdateSubConnState() called, finds the balancerCurrent, gives up lock, updateState comes in, causes Close() on balancerCurrent before the UpdateSubConnState is called on the balancerCurrent. mu sync.Mutex mu protects the following fields and all fields within balancerCurrent and balancerPending. mu does not need to be held when calling into the child balancers, as all calls into these children happen only as a direct result of a call into the gracefulSwitchBalancer, which are also guaranteed to be synchronous. There is one exception: an UpdateState call from a child balancer when current and pending are populated can lead to calling Close() on the current. To prevent that racing with an UpdateSubConnState from the channel, we hold currentMu during Close and UpdateSubConnState calls. Methods (total 11, in which 6 are exported) (*Balancer) Close() Close closes any active child balancers. (*Balancer) ExitIdle() ExitIdle forwards the call to the latest balancer created. If the latest balancer does not support ExitIdle, the subConns are re-connected to manually. (*Balancer) ResolverError(err error) ResolverError forwards the error to the latest balancer created. (*Balancer) SwitchTo(builder balancer.Builder) error SwitchTo initializes the graceful switch process, which completes based on connectivity state changes on the current/pending balancer. Thus, the switch process is not complete when this method returns. This method must be called synchronously alongside the rest of the balancer.Balancer methods this Graceful Switch Balancer implements. Deprecated: use ParseConfig and pass a parsed config to UpdateClientConnState to cause the Balancer to automatically change to the new child when necessary. (*Balancer) UpdateClientConnState(state balancer.ClientConnState) error UpdateClientConnState forwards the update to the latest balancer created. If the state's BalancerConfig is the config returned by a call to gracefulswitch.ParseConfig, then this function will automatically SwitchTo the balancer indicated by the config before forwarding its config to it, if necessary. (*Balancer) UpdateSubConnState(sc balancer.SubConn, state balancer.SubConnState) UpdateSubConnState forwards the update to the appropriate child. /* 5 unexporteds ... *//* 5 unexporteds: */ (*Balancer) balancerCurrentOrPending(bw *balancerWrapper) bool Helper function that checks if the balancer passed in is current or pending. The caller must hold gsb.mu. (*Balancer) latestBalancer() *balancerWrapper Returns nil if the graceful switch balancer is closed. (*Balancer) swap() swap swaps out the current lb with the pending lb and updates the ClientConn. The caller must hold gsb.mu. (*Balancer) switchTo(builder balancer.Builder) (*balancerWrapper, error) (*Balancer) updateSubConnState(sc balancer.SubConn, state balancer.SubConnState, cb func(balancer.SubConnState)) updateSubConnState forwards the update to the appropriate child. Implements (at least 3, all are exported) *Balancer : google.golang.org/grpc/balancer.Balancer *Balancer : google.golang.org/grpc/balancer.ExitIdler *Balancer : google.golang.org/grpc/balancer/endpointsharding.ExitIdler As Outputs Of (at least one exported) func NewBalancer(cc balancer.ClientConn, opts balancer.BuildOptions) *Balancer /* 2 unexporteds ... *//* 2 unexporteds: */ type balancerWrapper (struct) balancerWrapper wraps a balancer.Balancer, and overrides some Balancer methods to help cleanup SubConns created by the wrapped balancer. It implements the balancer.ClientConn interface and is passed down in that capacity to the wrapped balancer. It maintains a set of subConns created by the wrapped balancer and calls from the latter to create/update/shutdown SubConns update this set before being forwarded to the parent ClientConn. State updates from the wrapped balancer can result in invocation of the graceful switch logic. Fields (total 6, in which 2 are exported) Balancer balancer.Balancer ClientConn balancer.ClientConn /* 4 unexporteds ... *//* 4 unexporteds: */ builder balancer.Builder gsb *Balancer lastState balancer.State subconns map[balancer.SubConn]bool // subconns created by this balancer Methods (total 13, in which 12 are exported) (*balancerWrapper) Close() Close closes the underlying LB policy and shuts down the subconns it created. bw must not be referenced via balancerCurrent or balancerPending in gsb when called. gsb.mu must not be held. Does not panic with a nil receiver. ( balancerWrapper) ExitIdle() 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. ( balancerWrapper) MetricsRecorder() estats.MetricsRecorder 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. (*balancerWrapper) NewSubConn(addrs []resolver.Address, opts balancer.NewSubConnOptions) (balancer.SubConn, error) (*balancerWrapper) RemoveSubConn(sc balancer.SubConn) (*balancerWrapper) ResolveNow(opts resolver.ResolveNowOptions) ( balancerWrapper) ResolverError(error) ResolverError is called by gRPC when the name resolver reports an error. ( balancerWrapper) Target() string Target returns the dial target for this ClientConn. Deprecated: Use the Target field in the BuildOptions instead. (*balancerWrapper) UpdateAddresses(sc balancer.SubConn, addrs []resolver.Address) ( balancerWrapper) UpdateClientConnState(balancer.ClientConnState) 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. (*balancerWrapper) UpdateState(state balancer.State) ( balancerWrapper) UpdateSubConnState(balancer.SubConn, balancer.SubConnState) UpdateSubConnState is called by gRPC when the state of a SubConn changes. Deprecated: Use NewSubConnOptions.StateListener when creating the SubConn instead. /* one unexported ... *//* one unexported: */ ( balancerWrapper) enforceClientConnEmbedding() Implements (at least 6, all are exported) balancerWrapper : google.golang.org/grpc/internal.EnforceClientConnEmbedding *balancerWrapper : google.golang.org/grpc/balancer.Balancer *balancerWrapper : google.golang.org/grpc/balancer.ClientConn balancerWrapper : google.golang.org/grpc/balancer.ExitIdler balancerWrapper : google.golang.org/grpc/balancer/endpointsharding.ExitIdler *balancerWrapper : google.golang.org/grpc/resolver.Resolver As Outputs Of (at least 2, neither is exported) /* 2+ unexporteds ... *//* 2+ unexporteds: */ func (*Balancer).latestBalancer() *balancerWrapper func (*Balancer).switchTo(builder balancer.Builder) (*balancerWrapper, error) As Inputs Of (at least one unexported) /* at least one unexported ... *//* at least one unexported: */ func (*Balancer).balancerCurrentOrPending(bw *balancerWrapper) bool type lbConfig (struct) Fields (total 3, in which 1 is exported) LoadBalancingConfig serviceconfig.LoadBalancingConfig /* 2 unexporteds ... *//* 2 unexporteds: */ childBuilder balancer.Builder childConfig serviceconfig.LoadBalancingConfig Methods (only one, which is unexported) /* one unexported ... *//* one unexported: */ ( lbConfig) isLoadBalancingConfig() Implements (at least one exported) lbConfig : google.golang.org/grpc/serviceconfig.LoadBalancingConfig Package-Level Functions (total 3, all are exported) func ChildName(l serviceconfig.LoadBalancingConfig) string ChildName returns the name of the child balancer of the gracefulswitch Balancer. func NewBalancer(cc balancer.ClientConn, opts balancer.BuildOptions) *Balancer NewBalancer returns a graceful switch Balancer. func ParseConfig(cfg json.RawMessage) (serviceconfig.LoadBalancingConfig, error) ParseConfig parses a child config list and returns a LB config for the gracefulswitch Balancer. cfg is expected to be a json.RawMessage containing a JSON array of LB policy names + configs as the format of the "loadBalancingConfig" field in ServiceConfig. It returns a type that should be passed to UpdateClientConnState in the BalancerConfig field. Package-Level Variables (only one, which is unexported) /* one unexported ... *//* one unexported: */ var errBalancerClosed error