{"id":15285835,"url":"https://github.com/inaka/worker_pool","last_synced_at":"2026-02-21T22:08:34.615Z","repository":{"id":4453094,"uuid":"5591660","full_name":"inaka/worker_pool","owner":"inaka","description":"Erlang worker pool","archived":false,"fork":false,"pushed_at":"2024-11-08T11:40:50.000Z","size":902,"stargazers_count":276,"open_issues_count":5,"forks_count":79,"subscribers_count":57,"default_branch":"main","last_synced_at":"2025-04-04T08:58:50.162Z","etag":null,"topics":["erlang","hacktoberfest","pool"],"latest_commit_sha":null,"homepage":"https://hex.pm/packages/worker_pool","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inaka.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["elbrujohalcon"],"custom":["https://www.buymeacoffee.com/elbrujohalcon"]}},"created_at":"2012-08-28T20:30:35.000Z","updated_at":"2024-11-13T10:38:59.000Z","dependencies_parsed_at":"2023-12-19T07:56:34.099Z","dependency_job_id":"ca564aa5-9a3f-4e74-9030-03ea5500abbd","html_url":"https://github.com/inaka/worker_pool","commit_stats":{"total_commits":424,"total_committers":44,"mean_commits":9.636363636363637,"dds":0.7665094339622641,"last_synced_commit":"cd2e97f12fc61a74a479ec2b2461bfbe3d886cbe"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fworker_pool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fworker_pool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fworker_pool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fworker_pool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inaka","download_url":"https://codeload.github.com/inaka/worker_pool/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248420135,"owners_count":21100320,"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":["erlang","hacktoberfest","pool"],"created_at":"2024-09-30T15:07:48.244Z","updated_at":"2025-10-19T19:47:31.304Z","avatar_url":"https://github.com/inaka.png","language":"Erlang","funding_links":["https://github.com/sponsors/elbrujohalcon","https://www.buymeacoffee.com/elbrujohalcon"],"categories":[],"sub_categories":[],"readme":"# Worker Pool [![Build Status](https://github.com/inaka/worker_pool/actions/workflows/erlang.yml/badge.svg)](https://github.com/inaka/worker_pool/actions/workflows/erlang.yml)[![codecov](https://codecov.io/github/inaka/worker_pool/graph/badge.svg?token=qNtgagGp1H)](https://codecov.io/github/inaka/worker_pool)\n\n\u003cimg src=\"https://img3.wikia.nocookie.net/__cb20140705120849/clubpenguin/images/thumb/f/ff/MINIONS.jpg/481px-MINIONS.jpg\" align=\"right\" style=\"float:right\" height=\"400\" /\u003e\n\nA pool of gen servers.\n\n## Abstract\n\nThe goal of **worker pool** is pretty straightforward: to provide a transparent way to manage a pool of workers and _do the best effort_ in balancing the load among them, distributing the tasks requested to the pool.\n\nYou can just replace your calls to the `gen_server` module with calls to the `wpool` module, i.e., wherever you had a `gen_server:call/N` now you put a `wpool:call/N`, and that’s it!\n\n## Installation\n\nWorker Pool is available on [Hex.pm](https://hex.pm/packages/worker_pool). To install, just add it to your dependencies in `rebar.config`:\n```erlang\n{deps, [{worker_pool, \"~\u003e 6.1\"}]}.\n```\nor in `mix.ers`\n```elixir\ndefp deps() do\n  [{:worker_pool, \"~\u003e 6.1\"}]\nend\n```\n\n## Documentation\n\nThe documentation can be generated from code using [rebar3_ex_doc](https://github.com/starbelly/rebar3_ex_doc) with `rebar3 ex_doc`. It is also available online in [Hexdocs](https://hexdocs.pm/worker_pool/).\n\nAll user functions are exposed through the [wpool module](https://hexdocs.pm/worker_pool/wpool.html).\n\nDetailed usage is also documented in the same [wpool module summary](https://hexdocs.pm/worker_pool/doc/wpool.html#content).\n\n## Examples\n\nSay your application needs a connection to a third-party service that is frequently used. You implement a `gen_server` called `my_server` that knows how to talk the third-party protocol and keeps the connection open, and your business logic uses this `my_server` as the API to interact with. But this server is not only a single-point-of-failure, but also a bottleneck.\n\nLet's pool this server!\n\n#### Starting the pool\n\nFirst we need to start the pool, instead of starting a single server. If your server was part of your supervision tree, and your supervisor had a child-spec like:\n```erlang\n    ChildSpec = #{id =\u003e my_server_name,\n      start =\u003e {my_server, start_link, Arguments},\n      restart =\u003e permanent,\n      shutdown =\u003e 5000,\n      type =\u003e worker}.\n```\n\nYou can now replace it by\n```erlang\n    WPoolOpts = [{worker, {my_server, Arguments}}],\n    ChildSpec = wpool:child_spec(my_server_name, WPoolOpts),\n```\n\n#### Using the pool\n\nNow that the pool is in place, wherever you've called the server, now you can simply call the pool: all code like the following\n```erlang\n    %% ...\n    gen_server:call(my_server, Request),\n    %% ...\n    gen_server:cast(my_server, Notify),\n    %% ...\n```\ncan simply be replaced by\n```erlang\n    %% ...\n    wpool:call(my_server, Request),\n    %% ...\n    wpool:cast(my_server, Notify),\n    %% ...\n```\n\nIf you want all the workers to get notified of an event (for example for consistency reasons), you can use:\n```erlang\n    wpool:broadcast(my_server, Request)\n```\n\nAnd if events have a partial ordering, that is, there is a subset of them were they should be processed in a strict ordering, for example requests by user `X` should be processed sequentially but how they interleave with other requests is irrelevant, you can use:\n```erlang\n    wpool:call(my_server, Request, {hash_worker, X})\n```\nand requests for `X` will always be sent to the same worker.\n\nAnd just like that, all your requests are now pooled!\n\nBy passing a more complex configuration in the `WPoolOpts` parameter, you can tweak many things, for example the number of workers (`t:wpool:workers()`), options to pass to OTP's the `gen_server` engine behind your code `t:wpool:worker_opt()`, the strategy to supervise all the workers (`t:wpool:strategy()`), register callbacks you want to be triggered on worker's events (`t:wpool:callbacks()`), and many more. See `t:wpool:option()` for all options available.\n\n#### Case studies used in production\n\nTo see how `wpool` is used you can check the [test](test) folder where you'll find many different scenarios exercised in the different suites.\n\nIf you want to see **worker_pool** in a _real life_ project, we recommend you to check [sumo_db](https://github.com/inaka/sumo_db), another open-source library from [Inaka](https://inaka.github.io/) that uses wpool intensively, or [MongooseIM](https://github.com/esl/MongooseIM), an Erlang Solutions' Messaging server that uses wpool in many different ways.\n\n## Benchmarks\n\n**wpool** comes with a very basic [benchmarker](https://github.com/inaka/worker_pool/blob/main/test/wpool_bench.erl) that let's you compare different strategies against the default `wpool_worker`. If you want to do the same in your project, you can use `wpool_bench` as a template and replace the worker and the tasks by your own ones.\n\n## Contact Us\n\nIf you find any **bugs** or have a **problem** while using this library, please [open an issue](https://github.com/inaka/worker_pool/issues/new) in this repo (or a pull request :)).\n\n## Requirements\n\n**Required OTP version 25** or higher. We only provide guarantees that the system runs on `OTP25+` since that's what we're testing it in, but the `minimum_otp_vsn` is `\"21\"` because some systems where **worker_pool** is integrated do require it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finaka%2Fworker_pool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finaka%2Fworker_pool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finaka%2Fworker_pool/lists"}