{"id":17335734,"url":"https://github.com/fufuok/balancer","last_synced_at":"2025-04-14T18:33:06.070Z","repository":{"id":57631901,"uuid":"410766096","full_name":"fufuok/balancer","owner":"fufuok","description":"โš–๏ธ Goroutine-safe, High-performance general load balancing algorithm library.","archived":false,"fork":false,"pushed_at":"2021-12-11T03:07:55.000Z","size":64,"stargazers_count":10,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-28T07:02:46.541Z","etag":null,"topics":["consistent-hash","load-balancing","smooth-weighted-round-robin","weighed-rand","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}},"created_at":"2021-09-27T06:25:09.000Z","updated_at":"2024-03-26T08:04:30.000Z","dependencies_parsed_at":"2022-08-31T12:03:32.237Z","dependency_job_id":null,"html_url":"https://github.com/fufuok/balancer","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fufuok%2Fbalancer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fufuok%2Fbalancer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fufuok%2Fbalancer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fufuok%2Fbalancer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fufuok","download_url":"https://codeload.github.com/fufuok/balancer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248937024,"owners_count":21186146,"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","load-balancing","smooth-weighted-round-robin","weighed-rand","weighted-round-robin"],"created_at":"2024-10-15T15:11:59.670Z","updated_at":"2025-04-14T18:33:06.047Z","avatar_url":"https://github.com/fufuok.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# โš–๏ธ load balancing algorithm library\n\nGoroutine-safe, High-performance general load balancing algorithm library.\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 **faster** load balancer that supports **interface()**, please refer to another library: [fufuok/load-balancer](https://github.com/fufuok/load-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/balancer\n```\n\n## โšก๏ธ Quickstart\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/fufuok/balancer\"\n)\n\nfunc main() {\n\twNodes := map[string]int{\n\t\t\"๐Ÿ’\": 5,\n\t\t\"๐Ÿ‹\": 3,\n\t\t\"๐Ÿ‰\": 1,\n\t\t\"๐Ÿฅ‘\": 0,\n\t}\n\tbalancer.Update(wNodes)\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\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}\n// for RoundRobin/Random/ConsistentHash\nnodes := []string{\"A\", \"B\", \"C\"}\n```\n\n1. use default balancer (WRR)\n\n WeightedRoundRobin is the default balancer algorithm.\n\n ```go\n balancer.Update(wNodes)\n ```\n\n2. use WeightedRoundRobin (WRR)\n\n ```go\n var lb balancer.Balancer\n lb = balancer.New(balancer.WeightedRoundRobin, wNodes, nil)\n \n // or\n lb = balancer.New(balancer.WeightedRoundRobin, nil, nil)\n lb.Update(wNodes)\n \n // or\n lb = balancer.NewWeightedRoundRobin(wNodes)\n \n // or\n lb = balancer.NewWeightedRoundRobin()\n lb.Update(wNodes)\n ```\n\n3. use SmoothWeightedRoundRobin (SWRR)\n\n ```go\n var lb balancer.Balancer\n lb = balancer.New(balancer.SmoothWeightedRoundRobin, wNodes, nil)\n \n // or\n lb = balancer.New(balancer.SmoothWeightedRoundRobin, nil, nil)\n lb.Update(wNodes)\n \n // or\n lb = balancer.NewSmoothWeightedRoundRobin(wNodes)\n \n // or\n lb = balancer.NewSmoothWeightedRoundRobin()\n lb.Update(wNodes)\n ```\n\n4. use WeightedRand (WR)\n\n ```go\n var lb balancer.Balancer\n lb = balancer.New(balancer.WeightedRand, wNodes, nil)\n \n // or\n lb = balancer.New(balancer.WeightedRand, nil, nil)\n lb.Update(wNodes)\n \n // or\n lb = balancer.NewWeightedRand(wNodes)\n \n // or\n lb = balancer.NewWeightedRand()\n lb.Update(wNodes)\n ```\n\n5. use ConsistentHash\n\n ```go\n var lb balancer.Balancer\n lb = balancer.New(balancer.ConsistentHash, nil, nodes)\n \n // or\n lb = balancer.New(balancer.ConsistentHash, nil, nil)\n lb.Update(nodes)\n \n // or\n lb = balancer.NewConsistentHash(nodes)\n \n // or\n lb = balancer.NewConsistentHash()\n lb.Update(nodes)\n ```\n\n6. use RoundRobin (RR)\n\n ```go\n var lb balancer.Balancer\n lb = balancer.New(balancer.RoundRobin, nil, nodes)\n \n // or\n lb = balancer.New(balancer.RoundRobin, nil, nil)\n lb.Update(nodes)\n \n // or\n lb = balancer.NewRoundRobin(nodes)\n \n // or\n lb = balancer.NewRoundRobin()\n lb.Update(nodes)\n ```\n\n7. use Random\n\n ```go\n var lb balancer.Balancer\n lb = balancer.New(balancer.Random, nil, nodes)\n \n // or\n lb = balancer.New(balancer.Random, nil, nil)\n lb.Update(nodes)\n \n // or\n lb = balancer.NewRandom(nodes)\n \n // or\n lb = balancer.NewRandom()\n lb.Update(nodes)\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// Add add an item to be selected.\n\t// weight is only used for WeightedRoundRobin/SmoothWeightedRoundRobin/WeightedRand, default: 1\n\tAdd(item string, weight ...int)\n\n\t// All get all items.\n\t// RoundRobin/Random/ConsistentHash: []string\n\t// WeightedRoundRobin/SmoothWeightedRoundRobin/WeightedRand: map[string]int\n\tAll() interface{}\n\n\t// Select gets next selected item.\n\t// key is only used for ConsistentHash\n\tSelect(key ...string) string\n\n\t// Name load balancer name.\n\tName() string\n\n\t// Remove remove an item.\n\t// asClean: clean up or remove only one\n\tRemove(item string, asClean ...bool) bool\n\n\t// RemoveAll remove all items.\n\tRemoveAll()\n\n\t// Reset reset the balancer.\n\tReset()\n\n\t// Update reinitialize the balancer items.\n\t// RoundRobin/Random/ConsistentHash: []string\n\t// WeightedRoundRobin/SmoothWeightedRoundRobin/WeightedRand: map[string]int\n\tUpdate(items interface{}) bool\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/balancer\ncpu: Intel(R) Xeon(R) Gold 6151 CPU @ 3.00GHz\nBenchmarkBalancer/WRR-10-4 37112553 30.34 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/SWRR-10-4 38851680 30.39 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/WR-10-4 36406916 33.15 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/Hash-10-4 31506262 37.60 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/RoundRobin-10-4 53076963 23.86 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/Random-10-4 64582524 18.02 ns/op 0 B/op 0 allocs/op\n\nBenchmarkBalancer/WRR-100-4 32221255 37.31 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/SWRR-100-4 7337542 165.6 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/WR-100-4 21253034 53.29 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/Hash-100-4 25851721 46.58 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/RoundRobin-100-4 51670482 22.59 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/Random-100-4 66175606 18.14 ns/op 0 B/op 0 allocs/op\n\nBenchmarkBalancer/WRR-1000-4 28502208 42.09 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/SWRR-1000-4 872499 1391 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/WR-1000-4 16595787 71.57 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/Hash-1000-4 19103568 63.47 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/RoundRobin-1000-4 52725135 23.05 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/Random-1000-4 66541184 18.24 ns/op 0 B/op 0 allocs/op\n\nBenchmarkBalancer/WRR-10000-4 27912939 42.67 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/SWRR-10000-4 86983 14019 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/WR-10000-4 12691062 92.73 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/Hash-10000-4 16084016 73.96 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/RoundRobin-10000-4 52327888 24.05 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/Random-10000-4 66457050 18.17 ns/op 0 B/op 0 allocs/op\n\nBenchmarkBalancer/WRR-100000-4 24896972 43.20 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/SWRR-100000-4 7046 173884 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/WR-100000-4 9491140 127.3 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/Hash-100000-4 16090567 76.46 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/RoundRobin-100000-4 49422337 24.06 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/Random-100000-4 62700792 18.52 ns/op 0 B/op 0 allocs/op\n\nBenchmarkBalancer/WRR-1000000-4 24038544 47.01 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/SWRR-1000000-4 381 3108476 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/WR-1000000-4 4863207 259.8 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/Hash-1000000-4 16194163 74.15 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/RoundRobin-1000000-4 52971156 22.70 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancer/Random-1000000-4 40018782 26.25 ns/op 0 B/op 0 allocs/op\n\nBenchmarkBalancerParallel/WRR-10-4 12663168 92.42 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/SWRR-10-4 12709807 94.45 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/WR-10-4 28055660 68.66 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/Hash-10-4 16188872 72.30 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/RoundRobin-10-4 13612167 91.14 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/Random-10-4 17698065 67.72 ns/op 0 B/op 0 allocs/op\n\nBenchmarkBalancerParallel/WRR-100-4 13133222 88.99 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/SWRR-100-4 6563328 181.4 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/WR-100-4 26578320 79.94 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/Hash-100-4 16083211 74.67 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/RoundRobin-100-4 12263182 91.64 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/Random-100-4 17741816 67.81 ns/op 0 B/op 0 allocs/op\n\nBenchmarkBalancerParallel/WRR-1000-4 11212780 104.0 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/SWRR-1000-4 805879 1474 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/WR-1000-4 15821539 72.37 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/Hash-1000-4 14478384 81.82 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/RoundRobin-1000-4 12103447 88.15 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/Random-1000-4 17729145 67.81 ns/op 0 B/op 0 allocs/op\n\nBenchmarkBalancerParallel/WRR-10000-4 10567130 105.9 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/SWRR-10000-4 81170 14685 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/WR-10000-4 14379578 78.16 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/Hash-10000-4 14215629 84.50 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/RoundRobin-10000-4 13372892 90.45 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/Random-10000-4 17676268 67.92 ns/op 0 B/op 0 allocs/op\n\nBenchmarkBalancerParallel/WRR-100000-4 11561236 110.4 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/SWRR-100000-4 6835 175792 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/WR-100000-4 22145756 54.60 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/Hash-100000-4 14285690 84.04 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/RoundRobin-100000-4 12744205 90.57 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/Random-100000-4 17859376 67.19 ns/op 0 B/op 0 allocs/op\n\nBenchmarkBalancerParallel/WRR-1000000-4 11473530 109.0 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/SWRR-1000000-4 379 3127391 ns/op 7 B/op 0 allocs/op\nBenchmarkBalancerParallel/WR-1000000-4 10868928 100.4 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/Hash-1000000-4 14018941 85.23 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/RoundRobin-1000000-4 11614006 87.05 ns/op 0 B/op 0 allocs/op\nBenchmarkBalancerParallel/Random-1000000-4 17565664 68.35 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%2Fbalancer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffufuok%2Fbalancer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffufuok%2Fbalancer/lists"}