balancergroup

Documentation

Overview

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

Index

• type BalancerGroup
  • func New(opts Options) *BalancerGroup
  • func (bg *BalancerGroup) Add(id string, builder balancer.Builder)
  • func (bg *BalancerGroup) AddWithClientConn(id, balancerName string, cc balancer.ClientConn) error
  • func (bg *BalancerGroup) Close()
  • func (bg *BalancerGroup) ExitIdle()
  • func (bg *BalancerGroup) ExitIdleOne(id string)
  • func (bg *BalancerGroup) Remove(id string)
  • func (bg *BalancerGroup) ResolverError(err error)
  • func (bg *BalancerGroup) Start()
  • func (bg *BalancerGroup) UpdateBuilder(id string, builder balancer.Builder)
  • func (bg *BalancerGroup) UpdateClientConnState(id string, s balancer.ClientConnState) error
  • func (bg *BalancerGroup) UpdateSubConnState(sc balancer.SubConn, state balancer.SubConnState)
• type BalancerStateAggregator
• type Options

Types

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

func New(opts Options) *BalancerGroup

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) AddWithClientConn

func (bg *BalancerGroup) AddWithClientConn(id, balancerName string, cc balancer.ClientConn) error

AddWithClientConn adds a balancer with the given id to the group. The balancer is built with a balancer builder registered with balancerName. The given ClientConn is passed to the newly built balancer instead of the onepassed to balancergroup.New().

TODO: Get rid of the existing Add() API and replace it with this.

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) ExitIdle

func (bg *BalancerGroup) ExitIdle()

ExitIdle should be invoked when the parent LB policy's ExitIdle is invoked. It will trigger this on all sub-balancers, or reconnect their subconns if not supported.

func (*BalancerGroup) ExitIdleOne

func (bg *BalancerGroup) ExitIdleOne(id string)

ExitIdleOne instructs the sub-balancer `id` to exit IDLE state, if appropriate and possible.

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) UpdateBuilder

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

UpdateBuilder updates the builder for a current child, starting the Graceful Switch process for that child.

TODO: update this API to take the name of the new builder instead.

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 parent to the aggregator implementation (instead via balancer group).

type Options

type Options struct {
	// CC is a reference to the parent balancer.ClientConn.
	CC balancer.ClientConn
	// BuildOpts contains build options to be used when creating sub-balancers.
	BuildOpts balancer.BuildOptions
	// StateAggregator is an implementation of the BalancerStateAggregator
	// interface to aggregate picker and connectivity states from sub-balancers.
	StateAggregator BalancerStateAggregator
	// Logger is a group specific prefix logger.
	Logger *grpclog.PrefixLogger
	// SubBalancerCloseTimeout is the amount of time deleted sub-balancers spend
	// in the idle cache. A value of zero here disables caching of deleted
	// sub-balancers.
	SubBalancerCloseTimeout time.Duration
}

Options wraps the arguments to be passed to the BalancerGroup ctor.