Package balancergroup implements a utility struct to bind multiple balancers into one balancer.



    This section is empty.


    View Source
    var DefaultSubBalancerCloseTimeout = 15 * time.Minute

      DefaultSubBalancerCloseTimeout is defined as a variable instead of const for testing.

      TODO: make it a parameter for New().


      This section is empty.


      type BalancerGroup

      type BalancerGroup struct {
      	// contains filtered or unexported fields

        BalancerGroup takes a list of balancers, and make them into one balancer.

        Note that this struct doesn't implement balancer.Balancer, because it's not intended to be used directly as a balancer. It's expected to be used as a sub-balancer manager by a high level balancer.

        Updates from ClientConn are forwarded to sub-balancers

        - service config update
           - Not implemented
        - address update
        - subConn state change
           - find the corresponding balancer and forward

        Actions from sub-balances are forwarded to parent ClientConn

        - new/remove SubConn
        - picker update and health states change
           - sub-pickers are sent to an aggregator provided by the parent, which
           will group them into a group-picker. The aggregated connectivity state is
           also handled by the aggregator.
        - resolveNow

        Sub-balancers are only built when the balancer group is started. If the balancer group is closed, the sub-balancers are also closed. And it's guaranteed that no updates will be sent to parent ClientConn from a closed balancer group.

        func New

          New creates a new BalancerGroup. Note that the BalancerGroup needs to be started to work.

          func (*BalancerGroup) Add

          func (bg *BalancerGroup) Add(id string, builder balancer.Builder)

            Add adds a balancer built by builder to the group, with given id.

            func (*BalancerGroup) Close

            func (bg *BalancerGroup) Close()

              Close closes the balancer. It stops sub-balancers, and removes the subconns. The BalancerGroup can be restarted later.

              func (*BalancerGroup) Remove

              func (bg *BalancerGroup) Remove(id string)

                Remove removes the balancer with id from the group.

                But doesn't close the balancer. The balancer is kept in a cache, and will be closed after timeout. Cleanup work (closing sub-balancer and removing subconns) will be done after timeout.

                func (*BalancerGroup) ResolverError

                func (bg *BalancerGroup) ResolverError(err error)

                  ResolverError forwards resolver errors to all sub-balancers.

                  func (*BalancerGroup) Start

                  func (bg *BalancerGroup) Start()

                    Start starts the balancer group, including building all the sub-balancers, and send the existing addresses to them.

                    A BalancerGroup can be closed and started later. When a BalancerGroup is closed, it can still receive address updates, which will be applied when restarted.

                    func (*BalancerGroup) UpdateClientConnState

                    func (bg *BalancerGroup) UpdateClientConnState(id string, s balancer.ClientConnState) error

                      UpdateClientConnState handles ClientState (including balancer config and addresses) from resolver. It finds the balancer and forwards the update.

                      func (*BalancerGroup) UpdateSubConnState

                      func (bg *BalancerGroup) UpdateSubConnState(sc balancer.SubConn, state balancer.SubConnState)

                        UpdateSubConnState handles the state for the subconn. It finds the corresponding balancer and forwards the update.

                        type BalancerStateAggregator

                        type BalancerStateAggregator interface {
                        	// UpdateState updates the state of the id.
                        	// It's up to the implementation whether this will trigger an update to the
                        	// parent ClientConn.
                        	UpdateState(id string, state balancer.State)

                          BalancerStateAggregator aggregates sub-picker and connectivity states into a state.

                          It takes care of merging sub-picker into one picker. The picking config is passed directly from the the parent to the aggregator implementation (instead via balancer group).