blob: 4192918b9e287474b7570e7550f2917b2887ee25 [file] [log] [blame]
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -07001/*
2 *
3 * Copyright 2017 gRPC authors.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 */
18
19// Package base defines a balancer base that can be used to build balancers with
20// different picking algorithms.
21//
22// The base balancer creates a new SubConn for each resolved address. The
23// provided picker will only be notified about READY SubConns.
24//
25// This package is the base of round_robin balancer, its purpose is to be used
26// to build round_robin like balancers with complex picking algorithms.
27// Balancers with more complicated logic should try to implement a balancer
28// builder from scratch.
29//
30// All APIs in this package are experimental.
31package base
32
33import (
34 "google.golang.org/grpc/balancer"
35 "google.golang.org/grpc/resolver"
36)
37
38// PickerBuilder creates balancer.Picker.
39type PickerBuilder interface {
40 // Build takes a slice of ready SubConns, and returns a picker that will be
41 // used by gRPC to pick a SubConn.
42 Build(readySCs map[resolver.Address]balancer.SubConn) balancer.Picker
43}
44
Arjun E K57a7fcb2020-01-30 06:44:45 +000045// V2PickerBuilder creates balancer.V2Picker.
46type V2PickerBuilder interface {
47 // Build returns a picker that will be used by gRPC to pick a SubConn.
48 Build(info PickerBuildInfo) balancer.V2Picker
49}
50
51// PickerBuildInfo contains information needed by the picker builder to
52// construct a picker.
53type PickerBuildInfo struct {
54 // ReadySCs is a map from all ready SubConns to the Addresses used to
55 // create them.
56 ReadySCs map[balancer.SubConn]SubConnInfo
57}
58
59// SubConnInfo contains information about a SubConn created by the base
60// balancer.
61type SubConnInfo struct {
62 Address resolver.Address // the address used to create this SubConn
63}
64
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070065// NewBalancerBuilder returns a balancer builder. The balancers
66// built by this builder will use the picker builder to build pickers.
67func NewBalancerBuilder(name string, pb PickerBuilder) balancer.Builder {
68 return NewBalancerBuilderWithConfig(name, pb, Config{})
69}
70
71// Config contains the config info about the base balancer builder.
72type Config struct {
73 // HealthCheck indicates whether health checking should be enabled for this specific balancer.
74 HealthCheck bool
75}
76
77// NewBalancerBuilderWithConfig returns a base balancer builder configured by the provided config.
78func NewBalancerBuilderWithConfig(name string, pb PickerBuilder, config Config) balancer.Builder {
79 return &baseBuilder{
80 name: name,
81 pickerBuilder: pb,
82 config: config,
83 }
84}
Arjun E K57a7fcb2020-01-30 06:44:45 +000085
86// NewBalancerBuilderV2 returns a base balancer builder configured by the provided config.
87func NewBalancerBuilderV2(name string, pb V2PickerBuilder, config Config) balancer.Builder {
88 return &baseBuilder{
89 name: name,
90 v2PickerBuilder: pb,
91 config: config,
92 }
93}