package pickfirstleaf

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

Dependency Relation
	imports 17 packages, and imported by 2 packages

Involved Source Files

	  d pickfirstleaf.go
		Package pickfirstleaf contains the pick_first load balancing policy which
		will be the universal leaf policy after dualstack changes are implemented.
		
		# Experimental
		
		Notice: This package is EXPERIMENTAL and may be changed or removed in a
		later release.
Package-Level Type Names (total 9, none are exported)

	/* sort exporteds by: alphabet | popularity */
	/* 9 unexporteds ... *//* 9 unexporteds: */
	 type addressList (struct)
		addressList manages sequentially iterating over addresses present in a list
		of endpoints. It provides a 1 dimensional view of the addresses present in
		the endpoints.
		This type is not safe for concurrent access.

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			addresses []resolver.Address
			idx int
		Methods (total 8, none are exported)
			/* 8 unexporteds ... *//* 8 unexporteds: */
			(*addressList) currentAddress() resolver.Address
				currentAddress returns the current address pointed to in the addressList.
				If the list is in an invalid state, it returns an empty address instead.

			(*addressList) hasNext() bool
				hasNext returns whether incrementing the addressList will result in moving
				past the end of the list. If the list has already moved past the end, it
				returns false.

			(*addressList) increment() bool
				increment moves to the next index in the address list.
				This method returns false if it went off the list, true otherwise.

			(*addressList) isValid() bool
			(*addressList) reset()
			(*addressList) seekTo(needle resolver.Address) bool
				seekTo returns false if the needle was not found and the current index was
				left unchanged.

			(*addressList) size() int
			(*addressList) updateAddrs(addrs []resolver.Address)

	 type enableHealthListenerKeyType (struct)
		enableHealthListenerKeyType is a unique key type used in resolver
		attributes to indicate whether the health listener usage is enabled.

	 type idlePicker (struct)
		idlePicker is used when the SubConn is IDLE and kicks the SubConn into
		CONNECTING when Pick is called.

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

	 type ipAddrFamily int (basic type)

		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func addressFamily(address string) ipAddrFamily
		As Types Of (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			const ipAddrFamilyUnknown
			const ipAddrFamilyV4
			const ipAddrFamilyV6

	 type pfConfig (struct)

		Fields (total 2, both are exported)
			LoadBalancingConfig serviceconfig.LoadBalancingConfig
			ShuffleAddressList bool
				If set to true, instructs the LB policy to shuffle the order of the list
				of endpoints received from the name resolver before attempting to
				connect to them.

		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			( pfConfig) isLoadBalancingConfig()
		Implements (at least one exported)
			 pfConfig : google.golang.org/grpc/serviceconfig.LoadBalancingConfig

	 type picker (struct)

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			err error
			result balancer.PickResult
		Methods (only one, which is exported)
			(*picker) Pick(balancer.PickInfo) (balancer.PickResult, error)
		Implements (at least one exported)
			*picker : google.golang.org/grpc/balancer.Picker

	 type pickfirstBalancer (struct)

		Fields (total 12, none are exported)
			/* 12 unexporteds ... *//* 12 unexporteds: */
			addressList addressList
			cancelConnectionTimer func()
			cc balancer.ClientConn
			firstPass bool
			healthCheckingEnabled bool
			logger *internalgrpclog.PrefixLogger
				The following fields are initialized at build time and read-only after
				that and therefore do not need to be guarded by a mutex.

			metricsRecorder expstats.MetricsRecorder
				// guaranteed to be non nil

			mu sync.Mutex
				The mutex is used to ensure synchronization of updates triggered
				from the idle picker and the already serialized resolver,
				SubConn state updates.

			numTF int
			state connectivity.State
				State reported to the channel based on SubConn states and resolver
				updates.

			subConns *resolver.AddressMapV2[*scData]
				scData for active subonns mapped by address.

			target string
		Methods (total 19, in which 5 are exported)
			(*pickfirstBalancer) Close()
			(*pickfirstBalancer) ExitIdle()
				ExitIdle moves the balancer out of idle state. It can be called concurrently
				by the idlePicker and clientConn so access to variables should be
				synchronized.

			(*pickfirstBalancer) ResolverError(err error)
				ResolverError is called by the ClientConn when the name resolver produces
				an error or when pickfirst determined the resolver update to be invalid.

			(*pickfirstBalancer) UpdateClientConnState(state balancer.ClientConnState) error
			(*pickfirstBalancer) UpdateSubConnState(subConn balancer.SubConn, state balancer.SubConnState)
				UpdateSubConnState is unused as a StateListener is always registered when
				creating SubConns.

			/* 14 unexporteds ... *//* 14 unexporteds: */
			(*pickfirstBalancer) closeSubConnsLocked()
			(*pickfirstBalancer) endFirstPassIfPossibleLocked(lastErr error)
				endFirstPassIfPossibleLocked ends the first happy-eyeballs pass if all the
				addresses are tried and their SubConns have reported a failure.

			(*pickfirstBalancer) forceUpdateConcludedStateLocked(newState balancer.State)
				forceUpdateConcludedStateLocked stores the state reported to the channel and
				calls ClientConn.UpdateState().
				A separate function is defined to force update the ClientConn state since the
				channel doesn't correctly assume that LB policies start in CONNECTING and
				relies on LB policy to send an initial CONNECTING update.

			(*pickfirstBalancer) isActiveSCData(sd *scData) bool
			(*pickfirstBalancer) newSCData(addr resolver.Address) (*scData, error)
			(*pickfirstBalancer) reconcileSubConnsLocked(newAddrs []resolver.Address)
				reconcileSubConnsLocked updates the active subchannels based on a new address
				list from the resolver. It does this by:
				  - closing subchannels: any existing subchannels associated with addresses
				    that are no longer in the updated list are shut down.
				  - removing subchannels: entries for these closed subchannels are removed
				    from the subchannel map.
				
				This ensures that the subchannel map accurately reflects the current set of
				addresses received from the name resolver.

			(*pickfirstBalancer) requestConnectionLocked()
				requestConnectionLocked starts connecting on the subchannel corresponding to
				the current address. If no subchannel exists, one is created. If the current
				subchannel is in TransientFailure, a connection to the next address is
				attempted until a subchannel is found.

			(*pickfirstBalancer) resolverErrorLocked(err error)
			(*pickfirstBalancer) scheduleNextConnectionLocked()
			(*pickfirstBalancer) shutdownRemainingLocked(selected *scData)
				shutdownRemainingLocked shuts down remaining subConns. Called when a subConn
				becomes ready, which means that all other subConn must be shutdown.

			(*pickfirstBalancer) startFirstPassLocked()
			(*pickfirstBalancer) updateBalancerState(newState balancer.State)
				updateBalancerState stores the state reported to the channel and calls
				ClientConn.UpdateState(). As an optimization, it avoids sending duplicate
				updates to the channel.

			(*pickfirstBalancer) updateSubConnHealthState(sd *scData, state balancer.SubConnState)
			(*pickfirstBalancer) updateSubConnState(sd *scData, newState balancer.SubConnState)
		Implements (at least 3, all are exported)
			*pickfirstBalancer : google.golang.org/grpc/balancer.Balancer
			*pickfirstBalancer : google.golang.org/grpc/balancer.ExitIdler
			*pickfirstBalancer : google.golang.org/grpc/balancer/endpointsharding.ExitIdler

	 type pickfirstBuilder (struct)

		Methods (total 3, all are exported)
			( pickfirstBuilder) Build(cc balancer.ClientConn, bo balancer.BuildOptions) balancer.Balancer
			( pickfirstBuilder) Name() string
			( pickfirstBuilder) ParseConfig(js json.RawMessage) (serviceconfig.LoadBalancingConfig, error)
		Implements (at least 2, both are exported)
			 pickfirstBuilder : google.golang.org/grpc/balancer.Builder
			 pickfirstBuilder : google.golang.org/grpc/balancer.ConfigParser

	 type scData (struct)
		scData keeps track of the current state of the subConn.
		It is not safe for concurrent access.

		Fields (total 6, none are exported)
			/* 6 unexporteds ... *//* 6 unexporteds: */
			addr resolver.Address
			connectionFailedInFirstPass bool
			effectiveState connectivity.State
				The effective connectivity state based on raw connectivity, health state
				and after following sticky TransientFailure behaviour defined in A62.

			lastErr error
			rawConnectivityState connectivity.State
			subConn balancer.SubConn
				The following fields are initialized at build time and read-only after
				that.



Package-Level Functions (total 6, in which 1 is exported)

	 func EnableHealthListener(state resolver.State) resolver.State
		EnableHealthListener updates the state to configure pickfirst for using a
		generic health listener.

	/* 5 unexporteds ... *//* 5 unexporteds: */
	 func addressFamily(address string) ipAddrFamily
		addressFamily returns the ipAddrFamily after parsing the address string.
		If the address isn't of the format "ip-address:port", it returns
		ipAddrFamilyUnknown. The address may be valid even if it's not an IP when
		using a resolver like passthrough where the address may be a hostname in
		some format that the dialer can resolve.

	 func deDupAddresses(addrs []resolver.Address) []resolver.Address
		deDupAddresses ensures that each address appears only once in the slice.

	 func equalAddressIgnoringBalAttributes(a, b *resolver.Address) bool
		equalAddressIgnoringBalAttributes returns true is a and b are considered
		equal. This is different from the Equal method on the resolver.Address type
		which considers all fields to determine equality. Here, we only consider
		fields that are meaningful to the SubConn.

	 func init()
	 func interleaveAddresses(addrs []resolver.Address) []resolver.Address
		interleaveAddresses interleaves addresses of both families (IPv4 and IPv6)
		as per RFC-8305 section 4.
		Whichever address family is first in the list is followed by an address of
		the other address family; that is, if the first address in the list is IPv6,
		then the first IPv4 address should be moved up in the list to be second in
		the list. It doesn't support configuring "First Address Family Count", i.e.
		there will always be a single member of the first address family at the
		beginning of the interleaved list.
		Addresses that are neither IPv4 nor IPv6 are treated as part of a third
		"unknown" family for interleaving.
		See: https://datatracker.ietf.org/doc/html/rfc8305#autoid-6


Package-Level Variables (total 5, in which 1 is exported)

	  var Name string
		Name is the name of the pick_first_leaf balancer.
		It is changed to "pick_first" in init() if this balancer is to be
		registered as the default pickfirst.

	/* 4 unexporteds ... *//* 4 unexporteds: */
	  var connectionAttemptsFailedMetric *stats.Int64CountHandle
	  var connectionAttemptsSucceededMetric *stats.Int64CountHandle
	  var disconnectionsMetric *stats.Int64CountHandle
	  var logger grpclog.DepthLoggerV2
Package-Level Constants (total 5, none are exported)

	/* 5 unexporteds ... *//* 5 unexporteds: */
	const connectionDelayInterval time.Duration = 250000000
		connectionDelayInterval is the time to wait for during the happy eyeballs
		pass before starting the next connection attempt.

	const ipAddrFamilyUnknown ipAddrFamily = 0
		ipAddrFamilyUnknown represents strings that can't be parsed as an IP
		address.

	const ipAddrFamilyV4 ipAddrFamily = 1
	const ipAddrFamilyV6 ipAddrFamily = 2
	const logPrefix = "[pick-first-leaf-lb %p] "
		TODO: change to pick-first when this becomes the default pick_first policy.

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