balancergroup

package
v1.62.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 21, 2024 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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 added in v1.51.0

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 added in v1.46.0

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 added in v1.58.0

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL