{"id":17335737,"url":"https://github.com/fufuok/load-balancer","last_synced_at":"2025-03-27T07:23:03.948Z","repository":{"id":112342611,"uuid":"417562792","full_name":"fufuok/load-balancer","owner":"fufuok","description":"⚡️ Faster, high-performance general load balancing algorithm library.","archived":false,"fork":false,"pushed_at":"2021-10-21T05:06:44.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-01T12:25:56.841Z","etag":null,"topics":["consistent-hash","weighted","weighted-random","weighted-round-robin"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fufuok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-15T16:14:44.000Z","updated_at":"2021-10-21T05:06:46.000Z","dependencies_parsed_at":"2023-05-17T09:31:37.863Z","dependency_job_id":null,"html_url":"https://github.com/fufuok/load-balancer","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fufuok%2Fload-balancer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fufuok%2Fload-balancer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fufuok%2Fload-balancer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fufuok%2Fload-balancer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fufuok","download_url":"https://codeload.github.com/fufuok/load-balancer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245798760,"owners_count":20674018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["consistent-hash","weighted","weighted-random","weighted-round-robin"],"created_at":"2024-10-15T15:12:00.272Z","updated_at":"2025-03-27T07:23:03.917Z","avatar_url":"https://github.com/fufuok.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚖️ load balancing algorithm library\n\nHigh-performance general load balancing algorithm library, non-goroutine-safe.\n\nSmooth 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.\n\n------\n\nIf you want a **goroutine-safe** load balancer, please refer to another library, which supports more APIs: [fufuok/balancer](https://github.com/fufuok/balancer)\n\n------\n\n## 🎯 Features\n\n- WeightedRoundRobin\n- SmoothWeightedRoundRobin\n- WeightedRand\n- ConsistentHash\n- RoundRobin\n- Random\n\n## ⚙️ Installation\n\n```go\ngo get -u github.com/fufuok/load-balancer\n```\n\n## ⚡️ Quickstart\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\tbalancer \"github.com/fufuok/load-balancer\"\n)\n\nfunc main() {\n\tchoices := []*balancer.Choice{\n\t\t{Item: \"🍒\", Weight: 5},\n\t\t{Item: \"🍋\", Weight: 3},\n\t\t{Item: \"🍉\", Weight: 1},\n\t\t{Item: \"🥑\", Weight: 0},\n\t}\n\tbalancer.Update(choices)\n\n\t// result of smooth selection is similar to: 🍒 🍒 🍒 🍋 🍒 🍋 🍒 🍋 🍉\n\tfor i := 0; i \u003c 9; i++ {\n\t\tfmt.Print(balancer.Select(), \" \")\n\t}\n\tfmt.Println()\n}\n```\n\n## 📚 Examples\n\nplease see: [examples](examples)\n\n### Initialize the balancer\n\nSample data:\n\n```go\nvar choices []*balancer.Choice\n\n// for WeightedRoundRobin/SmoothWeightedRoundRobin/WeightedRand\n// To be selected : Weighted\nwNodes := map[string]int{\n    \"A\": 5,\n    \"B\": 3,\n    \"C\": 1,\n    \"D\": 0,\n}\nchoices = balancer.NewChoicesMap(wNodes)\n\n// or\nchoices = []*balancer.Choice{\n    {Item: \"A\", Weight: 5},\n    {Item: \"B\", Weight: 3},\n    {Item: \"C\", Weight: 1},\n    {Item: \"D\", Weight: 0},\n}\n\n// for RoundRobin/Random/ConsistentHash\nnodes := []string{\"A\", \"B\", \"C\"}\nchoices = balancer.NewChoicesSlice(nodes)\n\n// or\nchoices = []*balancer.Choice{\n    {Item: \"A\"},\n    {Item: \"B\"},\n    {Item: \"C\"},\n}\n```\n\n1. use default balancer (WRR)\n\n   WeightedRoundRobin is the default balancer algorithm.\n\n   ```go\n   balancer.Update(choices)\n   ```\n\n2. use WeightedRoundRobin (WRR)\n\n   ```go\n   var lb balancer.Balancer\n   lb = balancer.New(balancer.WeightedRoundRobin, choices)\n   \n   // or\n   lb = balancer.New(balancer.WeightedRoundRobin, nil)\n   lb.Update(choices)\n   \n   // or\n   lb = balancer.NewWeightedRoundRobin(choices...)\n   \n   // or\n   lb = balancer.NewWeightedRoundRobin()\n   lb.Update(choices)\n   ```\n\n3. use SmoothWeightedRoundRobin (SWRR)\n\n   ```go\n   var lb balancer.Balancer\n   lb = balancer.New(balancer.SmoothWeightedRoundRobin, choices)\n   \n   // or\n   lb = balancer.New(balancer.SmoothWeightedRoundRobin, nil)\n   lb.Update(choices)\n   \n   // or\n   lb = balancer.NewSmoothWeightedRoundRobin(choices...)\n   \n   // or\n   lb = balancer.NewSmoothWeightedRoundRobin()\n   lb.Update(choices)\n   ```\n\n4. use WeightedRand (WR)\n\n   ```go\n   var lb balancer.Balancer\n   lb = balancer.New(balancer.WeightedRand, choices)\n   \n   // or\n   lb = balancer.New(balancer.WeightedRand, nil)\n   lb.Update(choices)\n   \n   // or\n   lb = balancer.NewWeightedRand(choices...)\n   \n   // or\n   lb = balancer.NewWeightedRand()\n   lb.Update(choices)\n   ```\n\n5. use ConsistentHash\n\n   ```go\n   var lb balancer.Balancer\n   lb = balancer.New(balancer.ConsistentHash, choices)\n   \n   // or\n   lb = balancer.New(balancer.ConsistentHash, nil)\n   lb.Update(choices)\n   \n   // or\n   lb = balancer.NewConsistentHash(choices...)\n   \n   // or\n   lb = balancer.NewConsistentHash()\n   lb.Update(choices)\n   ```\n\n6. use RoundRobin (RR)\n\n   ```go\n   var lb balancer.Balancer\n   lb = balancer.New(balancer.RoundRobin, choices)\n   \n   // or\n   lb = balancer.New(balancer.RoundRobin, nil)\n   lb.Update(choices)\n   \n   // or\n   lb = balancer.NewRoundRobin(choices...)\n   \n   // or\n   lb = balancer.NewRoundRobin()\n   lb.Update(choices)\n   ```\n\n7. use Random\n\n   ```go\n   var lb balancer.Balancer\n   lb = balancer.New(balancer.Random, choices)\n   \n   // or\n   lb = balancer.New(balancer.Random, nil)\n   lb.Update(choices)\n   \n   // or\n   lb = balancer.NewRandom(choices...)\n   \n   // or\n   lb = balancer.NewRandom()\n   lb.Update(choices)\n   ```\n\n### Gets next selected item\n\n```go\nnode := lb.Select()\n```\n\nip consistent hash:\n\n```go\nnode := lb.Select(\"192.168.1.100\")\nnode := lb.Select(\"192.168.1.100\", \"Test\", \"...\")\n```\n\n### Interface\n\n```go\ntype Balancer interface {\n\t// Select gets next selected item.\n\t// key is only used for ConsistentHash\n\tSelect(key ...string) interface{}\n\n\t// Name load balancer name.\n\tName() string\n\n\t// Update reinitialize the balancer items.\n\tUpdate(choices []*Choice) bool\n}\n\n// Choice to be selected for the load balancer\ntype Choice struct {\n\t// e.g. server addr / node / *url.URL\n\tItem interface{}\n\n\t// For WeightedRoundRobin / SmoothWeightedRoundRobin / WeightedRand\n\tWeight int\n\n\t// For SmoothWeightedRoundRobin, optional\n\tCurrentWeight int\n}\n```\n\n## 🤖 Benchmarks\n\n```shell\ngo test -run=^$ -benchmem -benchtime=1s -count=1 -bench=.\ngoos: linux\ngoarch: amd64\npkg: github.com/fufuok/load-balancer\ncpu: Intel(R) Xeon(R) Gold 6151 CPU @ 3.00GHz\nBenchmarkBalancer/WRR-10-4                         46217316                25.75 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/SWRR-10-4                        77468209                15.27 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/WR-10-4                          52319631                22.49 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/Hash-10-4                        39925784                30.21 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/RoundRobin-10-4                  66584161                18.14 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/Random-10-4                     242458752                4.904 ns/op            0 B/op          0 allocs/op\n\nBenchmarkBalancer/WRR-100-4                        40734304                30.44 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/SWRR-100-4                        7942176                152.7 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/WR-100-4                         31176547                38.46 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/Hash-100-4                       31901799                38.02 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/RoundRobin-100-4                 66206282                18.05 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/Random-100-4                    244788913                4.885 ns/op            0 B/op          0 allocs/op\n\nBenchmarkBalancer/WRR-1000-4                       34538292                34.18 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/SWRR-1000-4                        843820                 1320 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/WR-1000-4                        20156709                59.92 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/Hash-1000-4                      23270704                51.25 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/RoundRobin-1000-4                66487467                18.08 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/Random-1000-4                   221386104                5.098 ns/op            0 B/op          0 allocs/op\n\nBenchmarkBalancer/WRR-10000-4                      34621371                34.29 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/SWRR-10000-4                        88591                14274 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/WR-10000-4                       14898531                81.10 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/Hash-10000-4                     19238934                62.80 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/RoundRobin-10000-4               66228592                18.31 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/Random-10000-4                  191338644                6.872 ns/op            0 B/op          0 allocs/op\n\nBenchmarkBalancer/WRR-100000-4                     30867440                34.63 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/SWRR-100000-4                        6897               173933 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/WR-100000-4                      10732960                111.6 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/Hash-100000-4                    19251387                62.78 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/RoundRobin-100000-4              65002867                18.33 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/Random-100000-4                  88514517                13.07 ns/op            0 B/op          0 allocs/op\n\nBenchmarkBalancer/WRR-1000000-4                    28559396                36.27 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/SWRR-1000000-4                        363              3264391 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/WR-1000000-4                      4875242                238.9 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/Hash-1000000-4                   19132564                62.31 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/RoundRobin-1000000-4             64232452                18.44 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancer/Random-1000000-4                 25495011                45.96 ns/op            0 B/op          0 allocs/op\n\nBenchmarkBalancerParallel/WRR-10-4                 18472707                67.69 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/SWRR-10-4                 4228370                283.4 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/WR-10-4                 208656978                6.016 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/Hash-10-4               144690333                8.001 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/RoundRobin-10-4          19509270                61.33 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/Random-10-4             919527031                1.331 ns/op            0 B/op          0 allocs/op\n\nBenchmarkBalancerParallel/WRR-100-4                19207489                66.60 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/SWRR-100-4                1311392                899.7 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/WR-100-4                100000000                10.26 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/Hash-100-4              120191985                9.945 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/RoundRobin-100-4         18468038                62.90 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/Random-100-4            921913453                1.324 ns/op            0 B/op          0 allocs/op\n\nBenchmarkBalancerParallel/WRR-1000-4               17837187                68.50 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/SWRR-1000-4                534634                 2184 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/WR-1000-4                78022376                15.89 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/Hash-1000-4              87318837                13.83 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/RoundRobin-1000-4        18960835                61.85 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/Random-1000-4           214012765                5.450 ns/op            0 B/op          0 allocs/op\n\nBenchmarkBalancerParallel/WRR-10000-4              17449467                65.24 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/SWRR-10000-4               164738                 7878 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/WR-10000-4               56703684                20.90 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/Hash-10000-4             71464341                17.37 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/RoundRobin-10000-4       19946966                59.33 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/Random-10000-4          179242167                6.321 ns/op            0 B/op          0 allocs/op\n\nBenchmarkBalancerParallel/WRR-100000-4             17843058                63.60 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/SWRR-100000-4               17827                66743 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/WR-100000-4              41696436                29.32 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/Hash-100000-4            71783467                16.66 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/RoundRobin-100000-4      18777990                59.97 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/Random-100000-4         130029762                9.360 ns/op            0 B/op          0 allocs/op\n\nBenchmarkBalancerParallel/WRR-1000000-4            12799609                78.48 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/SWRR-1000000-4               1447               853293 ns/op            1 B/op          0 allocs/op\nBenchmarkBalancerParallel/WR-1000000-4             19860668                58.98 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/Hash-1000000-4           72376710                16.90 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/RoundRobin-1000000-4     19127218                62.03 ns/op            0 B/op          0 allocs/op\nBenchmarkBalancerParallel/Random-1000000-4         75088678                14.43 ns/op            0 B/op          0 allocs/op\n```\n\n## ⚠️ License\n\nThird-party library licenses:\n\n- [doublejump]([doublejump/LICENSE at master · edwingeng/doublejump (github.com)](https://github.com/edwingeng/doublejump/blob/master/LICENSE))\n- [go-jump]([go-jump/LICENSE at master · dgryski/go-jump (github.com)](https://github.com/dgryski/go-jump/blob/master/LICENSE))\n\n\n\n\n\n*ff*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffufuok%2Fload-balancer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffufuok%2Fload-balancer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffufuok%2Fload-balancer/lists"}