package grpclb

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

Dependency Relation
	imports 32 packages, and imported by one package

Involved Source Files

	   d➜ grpclb.go
		Package grpclb defines a grpclb balancer.

		To install grpclb balancer, import this package as:
		   import _ "google.golang.org/grpc/balancer/grpclb"

	      grpclb_config.go
	      grpclb_picker.go
	      grpclb_remote_balancer.go
	      grpclb_util.go
Package-Level Type Names (total 13, none are exported)

	/* sort exporteds by: alphabet | popularity */
	/* 13 unexporteds ... *//* 13 unexporteds: */
	 type balanceLoadClientStream (struct)

		Fields (only one, which is exported)
			ClientStream grpc.ClientStream
		Methods (total 8, all are exported)
			( T) CloseSend() error
				CloseSend closes the send direction of the stream. It closes the stream
				when non-nil error is met. It is also not safe to call CloseSend
				concurrently with SendMsg.

			( T) Context() context.Context
				Context returns the context for this stream.

				It should not be called until after Header or RecvMsg has returned. Once
				called, subsequent client-side retries are disabled.

			( T) Header() (metadata.MD, error)
				Header returns the header metadata received from the server if there
				is any. It blocks if the metadata is not ready to read.

			(*T) Recv() (*lbpb.LoadBalanceResponse, error)
			( T) RecvMsg(m interface{}) error
				RecvMsg blocks until it receives a message into m or the stream is
				done. It returns io.EOF when the stream completes successfully. On
				any other error, the stream is aborted and the error contains the RPC
				status.

				It is safe to have a goroutine calling SendMsg and another goroutine
				calling RecvMsg on the same stream at the same time, but it is not
				safe to call RecvMsg on the same stream in different goroutines.

			(*T) Send(m *lbpb.LoadBalanceRequest) error
			( T) SendMsg(m interface{}) error
				SendMsg is generally called by generated code. On error, SendMsg aborts
				the stream. If the error was generated by the client, the status is
				returned directly; otherwise, io.EOF is returned and the status of
				the stream may be discovered using RecvMsg.

				SendMsg blocks until:
				  - There is sufficient flow control to schedule m with the transport, or
				  - The stream is done, or
				  - The stream breaks.

				SendMsg does not wait until the message is received by the server. An
				untimely stream closure may result in lost messages. To ensure delivery,
				users should ensure the RPC completed successfully using RecvMsg.

				It is safe to have a goroutine calling SendMsg and another goroutine
				calling RecvMsg on the same stream at the same time, but it is not safe
				to call SendMsg on the same stream in different goroutines. It is also
				not safe to call CloseSend concurrently with SendMsg.

			( T) Trailer() metadata.MD
				Trailer returns the trailer metadata from the server, if there is any.
				It must only be called after stream.CloseAndRecv has returned, or
				stream.Recv has returned a non-nil error (including io.EOF).

		Implements (at least 3, all are exported)
			*T : google.golang.org/grpc/balancer/grpclb/grpc_lb_v1.LoadBalancer_BalanceLoadClient
			 T : google.golang.org/grpc.ClientStream
			 T : google.golang.org/grpc.Stream

	 type errPicker (struct)

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			err error
				Pick always returns this err.

		Methods (only one, which is exported)
			(*T) Pick(balancer.PickInfo) (balancer.PickResult, error)
		Implements (at least one exported)
			*T : google.golang.org/grpc/balancer.Picker

	 type grpclbServiceConfig (struct)

		Fields (total 2, both are exported)
			ChildPolicy *[]map[string]json.RawMessage
			LoadBalancingConfig serviceconfig.LoadBalancingConfig
		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			( T) isLoadBalancingConfig()
		Implements (at least one exported)
			 T : google.golang.org/grpc/serviceconfig.LoadBalancingConfig
		As Inputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func childIsPickFirst(sc *grpclbServiceConfig) bool

	 type lbBalancer (struct)

		Fields (total 24, none are exported)
			/* 24 unexporteds ... *//* 24 unexporteds: */
			backendAddrs []resolver.Address
				Backend addresses. It's kept so the addresses are available when
				switching between round_robin and pickfirst.

			backendAddrsWithoutMetadata []resolver.Address
				All backends addresses, with metadata set to nil. This list contains all
				backend addresses in the same order and with the same duplicates as in
				serverlist. When generating picker, a SubConn slice with the same order
				but with only READY SCs will be gerenated.

			backoff backoff.Strategy
				backoff for calling remote balancer.

			cc *lbCacheClientConn
			ccRemoteLB *remoteBalancerCCWrapper
				The ClientConn to talk to the remote balancer.

			clientStats *rpcStats
				Support client side load reporting. Each picker gets a reference to this,
				and will update its content.

			doneCh chan struct{}
			fallbackTimeout time.Duration
			fullServerList []*lbpb.Server
				The full server list including drops, used to check if the newly received
				serverList contains anything new. Each generate picker will also have
				reference to this list to do the first layer pick.

			grpclbBackendCreds credentials.Bundle
				grpclbBackendCreds is the creds bundle to be used for addresses that are
				returned by grpclb server. If it's nil, don't set anything when creating
				SubConns.

			grpclbClientConnCreds credentials.Bundle
				grpclbClientConnCreds is the creds bundle to be used to connect to grpclb
				servers. If it's nil, use the TransportCredentials from BuildOptions
				instead.

			inFallback bool
			manualResolver *lbManualResolver
				manualResolver is used in the remote LB ClientConn inside grpclb. When
				resolved address updates are received by grpclb, filtered updates will be
				send to remote LB ClientConn through this resolver.

			mu sync.Mutex
				// guards everything following.

			opt balancer.BuildOptions
			picker balancer.Picker
			remoteBalancerConnected bool
				Support fallback to resolved backend addresses if there's no response
				from remote balancer within fallbackTimeout.

			resolvedBackendAddrs []resolver.Address
				resolvedBackendAddrs is resolvedAddrs minus remote balancers. It's set
				when resolved address updates are received, and read in the goroutine
				handling fallback.

			scStates map[balancer.SubConn]connectivity.State
				// Used to filter READY SubConns.

			serverListReceived bool
			state connectivity.State
				Roundrobin functionalities.

			subConns map[resolver.Address]balancer.SubConn
				// Used to new/remove SubConn.

			target string
			usePickFirst bool
		Methods (total 12, in which 4 are exported)
			(*T) Close()
			(*T) ResolverError(error)
			(*T) UpdateClientConnState(ccs balancer.ClientConnState) error
			(*T) UpdateSubConnState(sc balancer.SubConn, scs balancer.SubConnState)
			/* 8 unexporteds ... *//* 8 unexporteds: */
			(*T) aggregateSubConnStates() connectivity.State
				aggregateSubConnStats calculate the aggregated state of SubConns in
				lb.SubConns. These SubConns are subconns in use (when switching between
				fallback and grpclb). lb.scState contains states for all SubConns, including
				those in cache (SubConns are cached for 10 seconds after remove).

				The aggregated state is:
				 - 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 the aggregated state is TransientFailure.

			(*T) fallbackToBackendsAfter(fallbackTimeout time.Duration)
				fallbackToBackendsAfter blocks for fallbackTimeout and falls back to use
				resolved backends (backends received from resolver, not from remote balancer)
				if no connection to remote balancers was successful.

			(*T) handleServiceConfig(gc *grpclbServiceConfig)
			(*T) newRemoteBalancerCCWrapper()
			(*T) processServerList(l *lbpb.ServerList)
				processServerList updates balancer's internal state, create/remove SubConns
				and regenerates picker using the received serverList.

			(*T) refreshSubConns(backendAddrs []resolver.Address, fallback bool, pickFirst bool)
				refreshSubConns creates/removes SubConns with backendAddrs, and refreshes
				balancer state and picker.

				Caller must hold lb.mu.

			(*T) regeneratePicker(resetDrop bool)
				regeneratePicker takes a snapshot of the balancer, and generates a picker from
				it. The picker
				 - always returns ErrTransientFailure if the balancer is in TransientFailure,
				 - does two layer roundrobin pick otherwise.
				Caller must hold lb.mu.

			(*T) updateStateAndPicker(forceRegeneratePicker bool, resetDrop bool)
				updateStateAndPicker re-calculate the aggregated state, and regenerate picker
				if overall state is changed.

				If forceRegeneratePicker is true, picker will be regenerated.

		Implements (at least one exported)
			*T : google.golang.org/grpc/balancer.Balancer

	 type lbBuilder (struct)

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			fallbackTimeout time.Duration
		Methods (total 3, all are exported)
			(*T) Build(cc balancer.ClientConn, opt balancer.BuildOptions) balancer.Balancer
			(*T) Name() string
			(*T) ParseConfig(lbConfig json.RawMessage) (serviceconfig.LoadBalancingConfig, error)
		Implements (at least 2, both are exported)
			*T : google.golang.org/grpc/balancer.Builder
			*T : google.golang.org/grpc/balancer.ConfigParser

	 type lbCacheClientConn (struct)
		lbCacheClientConn is a wrapper balancer.ClientConn with a SubConn cache.
		SubConns will be kept in cache for subConnCacheTime before being removed.

		Its new and remove methods are updated to do cache first.

		Fields (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			cc balancer.ClientConn
			mu sync.Mutex
			subConnCache map[resolver.Address]*subConnCacheEntry
				subConnCache only keeps subConns that are being deleted.

			subConnToAddr map[balancer.SubConn]resolver.Address
			timeout time.Duration
		Methods (total 4, in which 3 are exported)
			(*T) NewSubConn(addrs []resolver.Address, opts balancer.NewSubConnOptions) (balancer.SubConn, error)
			(*T) RemoveSubConn(sc balancer.SubConn)
			(*T) UpdateState(s balancer.State)
			/* one unexported ... *//* one unexported: */
			(*T) close()
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func newLBCacheClientConn(cc balancer.ClientConn) *lbCacheClientConn

	 type lbManualResolver (struct)
		lbManualResolver is used by the ClientConn inside grpclb. It's a manual
		resolver with a special ResolveNow() function.

		When ResolveNow() is called, it calls ResolveNow() on the parent ClientConn,
		so when grpclb client lose contact with remote balancers, the parent
		ClientConn's resolver will re-resolve.

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			ccb balancer.ClientConn
			ccr resolver.ClientConn
			scheme string
		Methods (total 5, all are exported)
			(*T) Build(_ resolver.Target, cc resolver.ClientConn, _ resolver.BuildOptions) (resolver.Resolver, error)
			(*T) Close()
				Close is a noop for Resolver.

			(*T) ResolveNow(o resolver.ResolveNowOptions)
				ResolveNow calls resolveNow on the parent ClientConn.

			(*T) Scheme() string
			(*T) UpdateState(s resolver.State)
				UpdateState calls cc.UpdateState.

		Implements (at least 2, both are exported)
			*T : google.golang.org/grpc/resolver.Builder
			*T : google.golang.org/grpc/resolver.Resolver

	 type lbPicker (struct)
		lbPicker does two layers of picks:

		First layer: roundrobin on all servers in serverList, including drops and backends.
		- If it picks a drop, the RPC will fail as being dropped.
		- If it picks a backend, do a second layer pick to pick the real backend.

		Second layer: roundrobin on all READY backends.

		It's guaranteed that len(serverList) > 0.

		Fields (total 6, none are exported)
			/* 6 unexporteds ... *//* 6 unexporteds: */
			mu sync.Mutex
			serverList []*lbpb.Server
			serverListNext int
			stats *rpcStats
			subConns []balancer.SubConn
				// The subConns that were READY when taking the snapshot.

			subConnsNext int
		Methods (total 2, in which 1 are exported)
			(*T) Pick(balancer.PickInfo) (balancer.PickResult, error)
			/* one unexported ... *//* one unexported: */
			(*T) updateReadySCs(readySCs []balancer.SubConn)
		Implements (at least one exported)
			*T : google.golang.org/grpc/balancer.Picker
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func newLBPicker(serverList []*lbpb.Server, readySCs []balancer.SubConn, stats *rpcStats) *lbPicker

	 type loadBalancerClient (struct)
		Client API for LoadBalancer service.
		Mostly copied from generated pb.go file.
		To avoid circular dependency.

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			cc *grpc.ClientConn
		Methods (only one, which is exported)
			(*T) BalanceLoad(ctx context.Context, opts ...grpc.CallOption) (*balanceLoadClientStream, error)

	 type remoteBalancerCCWrapper (struct)

		Fields (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			backoff backoff.Strategy
			cc *grpc.ClientConn
			done chan struct{}
			lb *lbBalancer
			wg sync.WaitGroup
				waitgroup to wait for all goroutines to exit.

		Methods (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			(*T) callRemoteBalancer() (backoff bool, _ error)
			(*T) close()
				close closed the ClientConn to remote balancer, and waits until all
				goroutines to finish.

			(*T) readServerList(s *balanceLoadClientStream) error
			(*T) sendLoadReport(s *balanceLoadClientStream, interval time.Duration)
			(*T) watchRemoteBalancer()

	 type rpcStats (struct)
		rpcStats is same as lbpb.ClientStats, except that numCallsDropped is a map
		instead of a slice.

		Fields (total 6, none are exported)
			/* 6 unexporteds ... *//* 6 unexporteds: */
			mu sync.Mutex
			numCallsDropped map[string]int64
				map load_balance_token -> num_calls_dropped

			numCallsFinished int64
			numCallsFinishedKnownReceived int64
			numCallsFinishedWithClientFailedToSend int64
			numCallsStarted int64
				Only access the following fields atomically.

		Methods (total 4, none are exported)
			/* 4 unexporteds ... *//* 4 unexporteds: */
			(*T) drop(token string)
			(*T) failedToSend()
			(*T) knownReceived()
			(*T) toClientStats() *lbpb.ClientStats
				toClientStats converts rpcStats to lbpb.ClientStats, and clears rpcStats.

		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func newRPCStats() *rpcStats
		As Inputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func newLBPicker(serverList []*lbpb.Server, readySCs []balancer.SubConn, stats *rpcStats) *lbPicker

	 type rrPicker (struct)
		rrPicker does roundrobin on subConns. It's typically used when there's no
		response from remote balancer, and grpclb falls back to the resolved
		backends.

		It guaranteed that len(subConns) > 0.

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			mu sync.Mutex
			subConns []balancer.SubConn
				// The subConns that were READY when taking the snapshot.

			subConnsNext int
		Methods (only one, which is exported)
			(*T) Pick(balancer.PickInfo) (balancer.PickResult, error)
		Implements (at least one exported)
			*T : google.golang.org/grpc/balancer.Picker
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func newRRPicker(readySCs []balancer.SubConn) *rrPicker

	 type subConnCacheEntry (struct)

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			abortDeleting bool
			cancel func()
			sc balancer.SubConn


Package-Level Functions (total 10, none are exported)

	/* 10 unexporteds ... *//* 10 unexporteds: */
	 func childIsPickFirst(sc *grpclbServiceConfig) bool
	 func convertDuration(d *durationpb.Duration) time.Duration
	 func init()
	 func isZeroStats(stats *lbpb.ClientStats) bool
	 func newLBBuilder() balancer.Builder
		newLBBuilder creates a builder for grpclb.

	 func newLBBuilderWithFallbackTimeout(fallbackTimeout time.Duration) balancer.Builder
		newLBBuilderWithFallbackTimeout creates a grpclb builder with the given
		fallbackTimeout. If no response is received from the remote balancer within
		fallbackTimeout, the backend addresses from the resolved address list will be
		used.

		Only call this function when a non-default fallback timeout is needed.

	 func newLBCacheClientConn(cc balancer.ClientConn) *lbCacheClientConn
	 func newLBPicker(serverList []*lbpb.Server, readySCs []balancer.SubConn, stats *rpcStats) *lbPicker
	 func newRPCStats() *rpcStats
	 func newRRPicker(readySCs []balancer.SubConn) *rrPicker
Package-Level Variables (total 2, neither is exported)

	/* 2 unexporteds ... *//* 2 unexporteds: */
	  var errServerTerminatedConnection error
	  var logger grpclog.DepthLoggerV2
Package-Level Constants (total 6, none are exported)

	/* 6 unexporteds ... *//* 6 unexporteds: */
	const defaultFallbackTimeout time.Duration = 10000000000
	const grpclbName = "grpclb"
	const lbTokenKey = "lb-token"
	const pickFirstName = "pick_first"
	const roundRobinName = "round_robin"
	const subConnCacheTime time.Duration = 10000000000

The pages are generated with Golds v0.3.2-preview. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.