github.com/fufuok/balancer@v1.0.0/README.md (about) 1 # โ๏ธ load balancing algorithm library 2 3 Goroutine-safe, High-performance general load balancing algorithm library. 4 5 Smooth weighted load balancing algorithm: [NGINX](https://github.com/phusion/nginx/commit/27e94984486058d73157038f7950a0a36ecc6e35) and [LVS](http://kb.linuxvirtualserver.org/wiki/Weighted_Round-Robin_Scheduling), Doublejump provides a revamped Google's jump consistent hash. 6 7 ------ 8 9 If you want a **faster** load balancer that supports **interface()**, please refer to another library: [fufuok/load-balancer](https://github.com/fufuok/load-balancer) 10 11 ------ 12 13 ## ๐ฏ Features 14 15 - WeightedRoundRobin 16 - SmoothWeightedRoundRobin 17 - WeightedRand 18 - ConsistentHash 19 - RoundRobin 20 - Random 21 22 ## โ๏ธ Installation 23 24 ```go 25 go get -u github.com/fufuok/balancer 26 ``` 27 28 ## โก๏ธ Quickstart 29 30 ```go 31 package main 32 33 import ( 34 "fmt" 35 36 "github.com/fufuok/balancer" 37 ) 38 39 func main() { 40 wNodes := map[string]int{ 41 "๐": 5, 42 "๐": 3, 43 "๐": 1, 44 "๐ฅ": 0, 45 } 46 balancer.Update(wNodes) 47 48 // result of smooth selection is similar to: ๐ ๐ ๐ ๐ ๐ ๐ ๐ ๐ ๐ 49 for i := 0; i < 9; i++ { 50 fmt.Print(balancer.Select(), " ") 51 } 52 fmt.Println() 53 } 54 ``` 55 56 ## ๐ Examples 57 58 please see: [examples](examples) 59 60 ### Initialize the balancer 61 62 Sample data: 63 64 ```go 65 // for WeightedRoundRobin/SmoothWeightedRoundRobin/WeightedRand 66 // To be selected : Weighted 67 wNodes := map[string]int{ 68 "A": 5, 69 "B": 3, 70 "C": 1, 71 "D": 0, 72 } 73 // for RoundRobin/Random/ConsistentHash 74 nodes := []string{"A", "B", "C"} 75 ``` 76 77 1. use default balancer (WRR) 78 79 WeightedRoundRobin is the default balancer algorithm. 80 81 ```go 82 balancer.Update(wNodes) 83 ``` 84 85 2. use WeightedRoundRobin (WRR) 86 87 ```go 88 var lb balancer.Balancer 89 lb = balancer.New(balancer.WeightedRoundRobin, wNodes, nil) 90 91 // or 92 lb = balancer.New(balancer.WeightedRoundRobin, nil, nil) 93 lb.Update(wNodes) 94 95 // or 96 lb = balancer.NewWeightedRoundRobin(wNodes) 97 98 // or 99 lb = balancer.NewWeightedRoundRobin() 100 lb.Update(wNodes) 101 ``` 102 103 3. use SmoothWeightedRoundRobin (SWRR) 104 105 ```go 106 var lb balancer.Balancer 107 lb = balancer.New(balancer.SmoothWeightedRoundRobin, wNodes, nil) 108 109 // or 110 lb = balancer.New(balancer.SmoothWeightedRoundRobin, nil, nil) 111 lb.Update(wNodes) 112 113 // or 114 lb = balancer.NewSmoothWeightedRoundRobin(wNodes) 115 116 // or 117 lb = balancer.NewSmoothWeightedRoundRobin() 118 lb.Update(wNodes) 119 ``` 120 121 4. use WeightedRand (WR) 122 123 ```go 124 var lb balancer.Balancer 125 lb = balancer.New(balancer.WeightedRand, wNodes, nil) 126 127 // or 128 lb = balancer.New(balancer.WeightedRand, nil, nil) 129 lb.Update(wNodes) 130 131 // or 132 lb = balancer.NewWeightedRand(wNodes) 133 134 // or 135 lb = balancer.NewWeightedRand() 136 lb.Update(wNodes) 137 ``` 138 139 5. use ConsistentHash 140 141 ```go 142 var lb balancer.Balancer 143 lb = balancer.New(balancer.ConsistentHash, nil, nodes) 144 145 // or 146 lb = balancer.New(balancer.ConsistentHash, nil, nil) 147 lb.Update(nodes) 148 149 // or 150 lb = balancer.NewConsistentHash(nodes) 151 152 // or 153 lb = balancer.NewConsistentHash() 154 lb.Update(nodes) 155 ``` 156 157 6. use RoundRobin (RR) 158 159 ```go 160 var lb balancer.Balancer 161 lb = balancer.New(balancer.RoundRobin, nil, nodes) 162 163 // or 164 lb = balancer.New(balancer.RoundRobin, nil, nil) 165 lb.Update(nodes) 166 167 // or 168 lb = balancer.NewRoundRobin(nodes) 169 170 // or 171 lb = balancer.NewRoundRobin() 172 lb.Update(nodes) 173 ``` 174 175 7. use Random 176 177 ```go 178 var lb balancer.Balancer 179 lb = balancer.New(balancer.Random, nil, nodes) 180 181 // or 182 lb = balancer.New(balancer.Random, nil, nil) 183 lb.Update(nodes) 184 185 // or 186 lb = balancer.NewRandom(nodes) 187 188 // or 189 lb = balancer.NewRandom() 190 lb.Update(nodes) 191 ``` 192 193 ### Gets next selected item 194 195 ```go 196 node := lb.Select() 197 ``` 198 199 ip consistent hash: 200 201 ```go 202 node := lb.Select("192.168.1.100") 203 node := lb.Select("192.168.1.100", "Test", "...") 204 ``` 205 206 ### Interface 207 208 ```go 209 type Balancer interface { 210 // Add add an item to be selected. 211 // weight is only used for WeightedRoundRobin/SmoothWeightedRoundRobin/WeightedRand, default: 1 212 Add(item string, weight ...int) 213 214 // All get all items. 215 // RoundRobin/Random/ConsistentHash: []string 216 // WeightedRoundRobin/SmoothWeightedRoundRobin/WeightedRand: map[string]int 217 All() interface{} 218 219 // Select gets next selected item. 220 // key is only used for ConsistentHash 221 Select(key ...string) string 222 223 // Name load balancer name. 224 Name() string 225 226 // Remove remove an item. 227 // asClean: clean up or remove only one 228 Remove(item string, asClean ...bool) bool 229 230 // RemoveAll remove all items. 231 RemoveAll() 232 233 // Reset reset the balancer. 234 Reset() 235 236 // Update reinitialize the balancer items. 237 // RoundRobin/Random/ConsistentHash: []string 238 // WeightedRoundRobin/SmoothWeightedRoundRobin/WeightedRand: map[string]int 239 Update(items interface{}) bool 240 } 241 ``` 242 243 ## ๐ค Benchmarks 244 245 ```shell 246 go test -run=^$ -benchmem -benchtime=1s -count=1 -bench=. 247 goos: linux 248 goarch: amd64 249 pkg: github.com/fufuok/balancer 250 cpu: Intel(R) Xeon(R) Gold 6151 CPU @ 3.00GHz 251 BenchmarkBalancer/WRR-10-4 37112553 30.34 ns/op 0 B/op 0 allocs/op 252 BenchmarkBalancer/SWRR-10-4 38851680 30.39 ns/op 0 B/op 0 allocs/op 253 BenchmarkBalancer/WR-10-4 36406916 33.15 ns/op 0 B/op 0 allocs/op 254 BenchmarkBalancer/Hash-10-4 31506262 37.60 ns/op 0 B/op 0 allocs/op 255 BenchmarkBalancer/RoundRobin-10-4 53076963 23.86 ns/op 0 B/op 0 allocs/op 256 BenchmarkBalancer/Random-10-4 64582524 18.02 ns/op 0 B/op 0 allocs/op 257 258 BenchmarkBalancer/WRR-100-4 32221255 37.31 ns/op 0 B/op 0 allocs/op 259 BenchmarkBalancer/SWRR-100-4 7337542 165.6 ns/op 0 B/op 0 allocs/op 260 BenchmarkBalancer/WR-100-4 21253034 53.29 ns/op 0 B/op 0 allocs/op 261 BenchmarkBalancer/Hash-100-4 25851721 46.58 ns/op 0 B/op 0 allocs/op 262 BenchmarkBalancer/RoundRobin-100-4 51670482 22.59 ns/op 0 B/op 0 allocs/op 263 BenchmarkBalancer/Random-100-4 66175606 18.14 ns/op 0 B/op 0 allocs/op 264 265 BenchmarkBalancer/WRR-1000-4 28502208 42.09 ns/op 0 B/op 0 allocs/op 266 BenchmarkBalancer/SWRR-1000-4 872499 1391 ns/op 0 B/op 0 allocs/op 267 BenchmarkBalancer/WR-1000-4 16595787 71.57 ns/op 0 B/op 0 allocs/op 268 BenchmarkBalancer/Hash-1000-4 19103568 63.47 ns/op 0 B/op 0 allocs/op 269 BenchmarkBalancer/RoundRobin-1000-4 52725135 23.05 ns/op 0 B/op 0 allocs/op 270 BenchmarkBalancer/Random-1000-4 66541184 18.24 ns/op 0 B/op 0 allocs/op 271 272 BenchmarkBalancer/WRR-10000-4 27912939 42.67 ns/op 0 B/op 0 allocs/op 273 BenchmarkBalancer/SWRR-10000-4 86983 14019 ns/op 0 B/op 0 allocs/op 274 BenchmarkBalancer/WR-10000-4 12691062 92.73 ns/op 0 B/op 0 allocs/op 275 BenchmarkBalancer/Hash-10000-4 16084016 73.96 ns/op 0 B/op 0 allocs/op 276 BenchmarkBalancer/RoundRobin-10000-4 52327888 24.05 ns/op 0 B/op 0 allocs/op 277 BenchmarkBalancer/Random-10000-4 66457050 18.17 ns/op 0 B/op 0 allocs/op 278 279 BenchmarkBalancer/WRR-100000-4 24896972 43.20 ns/op 0 B/op 0 allocs/op 280 BenchmarkBalancer/SWRR-100000-4 7046 173884 ns/op 0 B/op 0 allocs/op 281 BenchmarkBalancer/WR-100000-4 9491140 127.3 ns/op 0 B/op 0 allocs/op 282 BenchmarkBalancer/Hash-100000-4 16090567 76.46 ns/op 0 B/op 0 allocs/op 283 BenchmarkBalancer/RoundRobin-100000-4 49422337 24.06 ns/op 0 B/op 0 allocs/op 284 BenchmarkBalancer/Random-100000-4 62700792 18.52 ns/op 0 B/op 0 allocs/op 285 286 BenchmarkBalancer/WRR-1000000-4 24038544 47.01 ns/op 0 B/op 0 allocs/op 287 BenchmarkBalancer/SWRR-1000000-4 381 3108476 ns/op 0 B/op 0 allocs/op 288 BenchmarkBalancer/WR-1000000-4 4863207 259.8 ns/op 0 B/op 0 allocs/op 289 BenchmarkBalancer/Hash-1000000-4 16194163 74.15 ns/op 0 B/op 0 allocs/op 290 BenchmarkBalancer/RoundRobin-1000000-4 52971156 22.70 ns/op 0 B/op 0 allocs/op 291 BenchmarkBalancer/Random-1000000-4 40018782 26.25 ns/op 0 B/op 0 allocs/op 292 293 BenchmarkBalancerParallel/WRR-10-4 12663168 92.42 ns/op 0 B/op 0 allocs/op 294 BenchmarkBalancerParallel/SWRR-10-4 12709807 94.45 ns/op 0 B/op 0 allocs/op 295 BenchmarkBalancerParallel/WR-10-4 28055660 68.66 ns/op 0 B/op 0 allocs/op 296 BenchmarkBalancerParallel/Hash-10-4 16188872 72.30 ns/op 0 B/op 0 allocs/op 297 BenchmarkBalancerParallel/RoundRobin-10-4 13612167 91.14 ns/op 0 B/op 0 allocs/op 298 BenchmarkBalancerParallel/Random-10-4 17698065 67.72 ns/op 0 B/op 0 allocs/op 299 300 BenchmarkBalancerParallel/WRR-100-4 13133222 88.99 ns/op 0 B/op 0 allocs/op 301 BenchmarkBalancerParallel/SWRR-100-4 6563328 181.4 ns/op 0 B/op 0 allocs/op 302 BenchmarkBalancerParallel/WR-100-4 26578320 79.94 ns/op 0 B/op 0 allocs/op 303 BenchmarkBalancerParallel/Hash-100-4 16083211 74.67 ns/op 0 B/op 0 allocs/op 304 BenchmarkBalancerParallel/RoundRobin-100-4 12263182 91.64 ns/op 0 B/op 0 allocs/op 305 BenchmarkBalancerParallel/Random-100-4 17741816 67.81 ns/op 0 B/op 0 allocs/op 306 307 BenchmarkBalancerParallel/WRR-1000-4 11212780 104.0 ns/op 0 B/op 0 allocs/op 308 BenchmarkBalancerParallel/SWRR-1000-4 805879 1474 ns/op 0 B/op 0 allocs/op 309 BenchmarkBalancerParallel/WR-1000-4 15821539 72.37 ns/op 0 B/op 0 allocs/op 310 BenchmarkBalancerParallel/Hash-1000-4 14478384 81.82 ns/op 0 B/op 0 allocs/op 311 BenchmarkBalancerParallel/RoundRobin-1000-4 12103447 88.15 ns/op 0 B/op 0 allocs/op 312 BenchmarkBalancerParallel/Random-1000-4 17729145 67.81 ns/op 0 B/op 0 allocs/op 313 314 BenchmarkBalancerParallel/WRR-10000-4 10567130 105.9 ns/op 0 B/op 0 allocs/op 315 BenchmarkBalancerParallel/SWRR-10000-4 81170 14685 ns/op 0 B/op 0 allocs/op 316 BenchmarkBalancerParallel/WR-10000-4 14379578 78.16 ns/op 0 B/op 0 allocs/op 317 BenchmarkBalancerParallel/Hash-10000-4 14215629 84.50 ns/op 0 B/op 0 allocs/op 318 BenchmarkBalancerParallel/RoundRobin-10000-4 13372892 90.45 ns/op 0 B/op 0 allocs/op 319 BenchmarkBalancerParallel/Random-10000-4 17676268 67.92 ns/op 0 B/op 0 allocs/op 320 321 BenchmarkBalancerParallel/WRR-100000-4 11561236 110.4 ns/op 0 B/op 0 allocs/op 322 BenchmarkBalancerParallel/SWRR-100000-4 6835 175792 ns/op 0 B/op 0 allocs/op 323 BenchmarkBalancerParallel/WR-100000-4 22145756 54.60 ns/op 0 B/op 0 allocs/op 324 BenchmarkBalancerParallel/Hash-100000-4 14285690 84.04 ns/op 0 B/op 0 allocs/op 325 BenchmarkBalancerParallel/RoundRobin-100000-4 12744205 90.57 ns/op 0 B/op 0 allocs/op 326 BenchmarkBalancerParallel/Random-100000-4 17859376 67.19 ns/op 0 B/op 0 allocs/op 327 328 BenchmarkBalancerParallel/WRR-1000000-4 11473530 109.0 ns/op 0 B/op 0 allocs/op 329 BenchmarkBalancerParallel/SWRR-1000000-4 379 3127391 ns/op 7 B/op 0 allocs/op 330 BenchmarkBalancerParallel/WR-1000000-4 10868928 100.4 ns/op 0 B/op 0 allocs/op 331 BenchmarkBalancerParallel/Hash-1000000-4 14018941 85.23 ns/op 0 B/op 0 allocs/op 332 BenchmarkBalancerParallel/RoundRobin-1000000-4 11614006 87.05 ns/op 0 B/op 0 allocs/op 333 BenchmarkBalancerParallel/Random-1000000-4 17565664 68.35 ns/op 0 B/op 0 allocs/op 334 ``` 335 336 ## โ ๏ธ License 337 338 Third-party library licenses: 339 340 - [doublejump]([doublejump/LICENSE at master ยท edwingeng/doublejump (github.com)](https://github.com/edwingeng/doublejump/blob/master/LICENSE)) 341 - [go-jump]([go-jump/LICENSE at master ยท dgryski/go-jump (github.com)](https://github.com/dgryski/go-jump/blob/master/LICENSE)) 342 343 344 345 346 347 *ff*