package balancer

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

Dependency Relation
	imports 11 packages, and imported by 5 packages

Involved Source Files

	   d➜ balancer.go
		Package balancer defines APIs for load balancing in gRPC.
		All APIs in this package are experimental.
Package-Level Type Names (total 15, all are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Balancer (interface)
		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.

		Methods (total 4, all are exported)
			( T) Close()
				Close closes the balancer. The balancer is not required to call
				ClientConn.RemoveSubConn for its existing SubConns.

			( T) ResolverError(error)
				ResolverError is called by gRPC when the name resolver reports an error.

			( T) UpdateClientConnState(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.

			( T) UpdateSubConnState(SubConn, SubConnState)
				UpdateSubConnState is called by gRPC when the state of a SubConn
				changes.

		Implemented By (at least 3, none are exported)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			*google.golang.org/grpc/balancer/base.baseBalancer
			*google.golang.org/grpc/balancer/grpclb.lbBalancer
			*google.golang.org/grpc.pickfirstBalancer
		As Outputs Of (at least one exported)
			func Builder.Build(cc ClientConn, opts BuildOptions) Balancer

	 type Builder (interface)
		Builder creates a balancer.

		Methods (total 2, both are exported)
			( T) Build(cc ClientConn, opts BuildOptions) Balancer
				Build creates a new balancer with the ClientConn.

			( T) Name() string
				Name returns the name of balancers built by this builder.
				It will be used to pick balancers (for example in service config).

		Implemented By (at least 3, none are exported)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			*google.golang.org/grpc/balancer/base.baseBuilder
			*google.golang.org/grpc/balancer/grpclb.lbBuilder
			*google.golang.org/grpc.pickfirstBuilder
		As Outputs Of (at least 6, in which 2 are exported)
			func Get(name string) Builder
			func google.golang.org/grpc/balancer/base.NewBalancerBuilder(name string, pb base.PickerBuilder, config base.Config) Builder
			/* 4+ unexporteds ... *//* 4+ unexporteds: */
			func google.golang.org/grpc/balancer/grpclb.newLBBuilder() Builder
			func google.golang.org/grpc/balancer/grpclb.newLBBuilderWithFallbackTimeout(fallbackTimeout time.Duration) Builder
			func google.golang.org/grpc/balancer/roundrobin.newBuilder() Builder
			func google.golang.org/grpc.newPickfirstBuilder() Builder
		As Inputs Of (at least 2, in which 1 are exported)
			func Register(b Builder)
			/* at least one unexported ... *//* at least one unexported: */
			func google.golang.org/grpc.newCCBalancerWrapper(cc *grpc.ClientConn, b Builder, bopts BuildOptions) *grpc.ccBalancerWrapper

	 type BuildOptions (struct)
		BuildOptions contains additional information for Build.

		Fields (total 5, all are exported)
			ChannelzParentID int64
				ChannelzParentID is the entity parent's channelz unique identification number.

			CredsBundle credentials.Bundle
				CredsBundle is the credentials bundle that the Balancer can use.

			DialCreds credentials.TransportCredentials
				DialCreds is the transport credential the Balancer implementation can
				use to dial to a remote load balancer server. The Balancer implementations
				can ignore this if it does not need to talk to another party securely.

			Dialer func(context.Context, string) (net.Conn, error)
				Dialer is the custom dialer the Balancer implementation can use to dial
				to a remote load balancer server. The Balancer implementations
				can ignore this if it doesn't need to talk to remote balancer.

			Target resolver.Target
				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.

		As Inputs Of (at least 2, in which 1 are exported)
			func Builder.Build(cc ClientConn, opts BuildOptions) Balancer
			/* at least one unexported ... *//* at least one unexported: */
			func google.golang.org/grpc.newCCBalancerWrapper(cc *grpc.ClientConn, b Builder, bopts BuildOptions) *grpc.ccBalancerWrapper

	 type ClientConn (interface)
		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.

		Methods (total 5, all are exported)
			( T) NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
				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.

			( T) RemoveSubConn(SubConn)
				RemoveSubConn removes the SubConn from ClientConn.
				The SubConn will be shutdown.

			( T) ResolveNow(resolver.ResolveNowOptions)
				ResolveNow is called by balancer to notify gRPC to do a name resolving.

			( T) Target() string
				Target returns the dial target for this ClientConn.

				Deprecated: Use the Target field in the BuildOptions instead.

			( T) UpdateState(State)
				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.

		Implemented By (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			*google.golang.org/grpc.ccBalancerWrapper
		As Inputs Of (at least 2, in which 1 are exported)
			func Builder.Build(cc ClientConn, opts BuildOptions) Balancer
			/* at least one unexported ... *//* at least one unexported: */
			func google.golang.org/grpc/balancer/grpclb.newLBCacheClientConn(cc ClientConn) *grpclb.lbCacheClientConn

	 type ClientConnState (struct)
		ClientConnState describes the state of a ClientConn relevant to the
		balancer.

		Fields (total 2, both are exported)
			BalancerConfig serviceconfig.LoadBalancingConfig
				The parsed load balancing configuration returned by the builder's
				ParseConfig method, if implemented.

			ResolverState resolver.State
		As Inputs Of (at least one exported)
			func Balancer.UpdateClientConnState(ClientConnState) error

	 type ConfigParser (interface)
		ConfigParser parses load balancer configs.

		Methods (only one, which is exported)
			( T) ParseConfig(LoadBalancingConfigJSON json.RawMessage) (serviceconfig.LoadBalancingConfig, error)
				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.

		Implemented By (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			*google.golang.org/grpc/balancer/grpclb.lbBuilder

	 type ConnectivityStateEvaluator (struct)
		ConnectivityStateEvaluator takes the connectivity states of multiple SubConns
		and returns one aggregated connectivity state.

		It's not thread safe.

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			numConnecting uint64
				// Number of addrConns in connecting state.

			numReady uint64
				// Number of addrConns in ready state.

		Methods (only one, which is exported)
			(*T) RecordTransition(oldState, newState connectivity.State) connectivity.State
				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 the aggregated state is TransientFailure.

				Idle and Shutdown are not considered.


	 type DoneInfo (struct)
		DoneInfo contains additional information for done.

		Fields (total 5, all are exported)
			BytesReceived bool
				BytesReceived indicates if any byte has been received from the server.

			BytesSent bool
				BytesSent indicates if any bytes have been sent to the server.

			Err error
				Err is the rpc error the RPC finished with. It could be nil.

			ServerLoad interface{}
				ServerLoad is the load received from server. It's usually sent as part of
				trailing metadata.

				The only supported type now is *orca_v1.LoadReport.

			Trailer metadata.MD
				Trailer contains the metadata from the RPC's trailer, if present.


	 type NewSubConnOptions (struct)
		NewSubConnOptions contains options to create new SubConn.

		Fields (total 2, both are exported)
			CredsBundle credentials.Bundle
				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 bool
				HealthCheckEnabled indicates whether health check service should be
				enabled on this SubConn

		As Inputs Of (at least 2, in which 1 are exported)
			func ClientConn.NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
			/* at least one unexported ... *//* at least one unexported: */
			func google.golang.org/grpc.(*ClientConn).newAddrConn(addrs []resolver.Address, opts NewSubConnOptions) (*grpc.addrConn, error)

	 type Picker (interface)
		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().

		Methods (only one, which is exported)
			( T) Pick(info PickInfo) (PickResult, error)
				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.

		Implemented By (at least 6, none are exported)
			/* 6+ unexporteds ... *//* 6+ unexporteds: */
			*google.golang.org/grpc/balancer/base.errPicker
			*google.golang.org/grpc/balancer/grpclb.errPicker
			*google.golang.org/grpc/balancer/grpclb.lbPicker
			*google.golang.org/grpc/balancer/grpclb.rrPicker
			*google.golang.org/grpc/balancer/roundrobin.rrPicker
			*google.golang.org/grpc.picker
		As Outputs Of (at least 2, both are exported)
			func google.golang.org/grpc/balancer/base.NewErrPicker(err error) Picker
			func google.golang.org/grpc/balancer/base.PickerBuilder.Build(info base.PickerBuildInfo) Picker

	 type PickInfo (struct)
		PickInfo contains additional information for the Pick operation.

		Fields (total 2, both are exported)
			Ctx context.Context
				Ctx is the RPC's context, and may contain relevant RPC-level information
				like the outgoing header metadata.

			FullMethodName string
				FullMethodName is the method name that NewClientStream() is called
				with. The canonical format is /service/Method.

		As Inputs Of (at least one exported)
			func Picker.Pick(info PickInfo) (PickResult, error)

	 type PickResult (struct)
		PickResult contains information related to a connection chosen for an RPC.

		Fields (total 2, both are exported)
			Done func(DoneInfo)
				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.

			SubConn SubConn
				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.

		As Outputs Of (at least one exported)
			func Picker.Pick(info PickInfo) (PickResult, error)

	 type State (struct)
		State contains the balancer's state relevant to the gRPC ClientConn.

		Fields (total 2, both are exported)
			ConnectivityState connectivity.State
				State contains the connectivity state of the balancer, which is used to
				determine the state of the ClientConn.

			Picker Picker
				Picker is used to choose connections (SubConns) for RPCs.

		As Inputs Of (at least one exported)
			func ClientConn.UpdateState(State)

	 type SubConn (interface)
		SubConn represents a gRPC sub connection.
		Each sub connection contains a list of addresses. gRPC will
		try to connect to them (in sequence), and stop trying the
		remainder once one connection is successful.

		The reconnect backoff will be applied on the list, not a single address.
		For example, try_on_all_addresses -> backoff -> try_on_all_addresses.

		All SubConns start in IDLE, and will not try to connect. To trigger
		the connecting, Balancers must call Connect.
		When the connection encounters an error, it will reconnect immediately.
		When the connection becomes IDLE, it will not reconnect unless Connect is
		called.

		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.

		Methods (total 2, both are exported)
			( T) Connect()
				Connect starts the connecting for this SubConn.

			( T) UpdateAddresses([]resolver.Address)
				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 closed, and
				a new connection will be created.

				This will trigger a state transition for the SubConn.

		Implemented By (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			*google.golang.org/grpc.acBalancerWrapper
		As Outputs Of (at least one exported)
			func ClientConn.NewSubConn([]resolver.Address, NewSubConnOptions) (SubConn, error)
		As Inputs Of (at least 5, in which 2 are exported)
			func Balancer.UpdateSubConnState(SubConn, SubConnState)
			func ClientConn.RemoveSubConn(SubConn)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			func google.golang.org/grpc/balancer/grpclb.newLBPicker(serverList []*lbpb.Server, readySCs []SubConn, stats *grpclb.rpcStats) *grpclb.lbPicker
			func google.golang.org/grpc/balancer/grpclb.newRRPicker(readySCs []SubConn) *grpclb.rrPicker
			func google.golang.org/grpc.(*ClientConn).handleSubConnStateChange(sc SubConn, s connectivity.State, err error)

	 type SubConnState (struct)
		SubConnState describes the state of a SubConn.

		Fields (total 2, both are exported)
			ConnectionError error
				ConnectionError is set if the ConnectivityState is TransientFailure,
				describing the reason the SubConn failed.  Otherwise, it is nil.

			ConnectivityState connectivity.State
				ConnectivityState is the connectivity state of the SubConn.

		As Inputs Of (at least one exported)
			func Balancer.UpdateSubConnState(SubConn, SubConnState)


Package-Level Functions (total 5, in which 3 are exported)

	 func Get(name string) 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.

	 func Register(b Builder)
		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.

	 func TransientFailureError(e error) error
		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.

	/* 2 unexporteds ... *//* 2 unexporteds: */
	 func init()
	 func unregisterForTesting(name string)
		unregisterForTesting deletes the balancer with the given name from the
		balancer map.

		This function is not thread-safe.


Package-Level Variables (total 4, in which 3 are exported)

	  var ErrBadResolverState error
		ErrBadResolverState may be returned by UpdateClientConnState to indicate a
		problem with the provided name resolver data.

	  var ErrNoSubConnAvailable error
		ErrNoSubConnAvailable indicates no SubConn is available for pick().
		gRPC will block the RPC until a new picker is available via UpdateState().

	  var ErrTransientFailure error
		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.

	/* one unexported ... *//* one unexported: */
	  var m map[string]Builder
		m is a map from name to balancer builder.

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.