package gracefulswitch

Import Path
	google.golang.org/grpc/internal/balancer/gracefulswitch (on go.dev)

Dependency Relation
	imports 7 packages, and imported by one package

Involved Source Files

	   #d gracefulswitch.go
		Package gracefulswitch implements a graceful switch load balancer.
Package-Level Type Names (total 2, in which 1 are 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 9, 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.

			(*Balancer) UpdateClientConnState(state balancer.ClientConnState) error
				UpdateClientConnState forwards the update to the latest balancer created.

			(*Balancer) UpdateSubConnState(sc balancer.SubConn, state balancer.SubConnState)
				UpdateSubConnState forwards the update to the appropriate child.

			/* 3 unexporteds ... *//* 3 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.

		Implements (at least 2, both are exported)
			*Balancer : google.golang.org/grpc/balancer.Balancer
			*Balancer : google.golang.org/grpc/balancer.ExitIdler
		As Outputs Of (at least one exported)
			func NewBalancer(cc balancer.ClientConn, opts balancer.BuildOptions) *Balancer

	/* one unexported ... *//* one unexported: */
	 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/remove
		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 4, in which 1 are exported)
			Balancer balancer.Balancer
			/* 3 unexporteds ... *//* 3 unexporteds: */
			gsb *Balancer
			lastState balancer.State
			subconns map[balancer.SubConn]bool
				// subconns created by this balancer

		Methods (total 10, all are exported)
			(*balancerWrapper) Close()
				Close closes the underlying LB policy and removes 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) 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
			(*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(sc balancer.SubConn, state balancer.SubConnState)
		Implements (at least 3, all are exported)
			*balancerWrapper : google.golang.org/grpc/balancer.Balancer
			*balancerWrapper : google.golang.org/grpc/balancer.ClientConn
			*balancerWrapper : google.golang.org/grpc/resolver.Resolver
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func (*Balancer).latestBalancer() *balancerWrapper
		As Inputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func (*Balancer).balancerCurrentOrPending(bw *balancerWrapper) bool


Package-Level Functions (only one, which is exported)

	 func NewBalancer(cc balancer.ClientConn, opts balancer.BuildOptions) *Balancer
		NewBalancer returns a graceful switch Balancer.


Package-Level Variables (only one, which is unexported)

	/* one unexported ... *//* one unexported: */
	  var errBalancerClosed error

The pages are generated with Golds v0.4.9. (GOOS=linux GOARCH=amd64)