Poolex

Poolex is a library for managing pools of workers. Inspired by poolboy.

See the Poolex Playground — interactive page to play with the library.

[!IMPORTANT]
Documentation on GitHub corresponds to the current branch. For stable versions' docs see Hexdocs.

Table of Contents

• Poolex
  • Table of Contents
  • Features
  • Requirements
  • Installation
  • Usage
  • Guides
  • Used by
  • Contributions
  • Support the Project

Features

Poolex makes working with worker pools easy and flexible:

• 🚀 Start multiple pools and grab a free worker from anywhere in your app.
• ⚡ Automatically spin up extra workers when the load grows.
• 📊 Get built-in metrics to monitor and tune your pools.
• 🛠️ Plug in your own logic for how workers and callers are managed.
• ⏳ Delay worker shutdowns to save resources when creating workers is expensive.

Why choose poolex over poolboy?

• Written in Elixir for a smoother experience in Elixir projects.
• Actively maintained and focused on modern Elixir needs.
• poolboy is a great library, but not actively maintained :crying_cat_face:

Requirements

Installation

Add :poolex to your list of dependencies in mix.exs:

def deps do
  [
    {:poolex, "~> 1.0"}
  ]
end

Usage

In the most typical use of Poolex, you only need to start a pool of workers as a child of your application.

children = [
  {Poolex,
    worker_module: SomeWorker,
    workers_count: 5}
]

Supervisor.start_link(children, strategy: :one_for_one)

Then you can execute any code on the workers with run/3:

iex> Poolex.run(SomeWorker, &(is_pid?(&1)), checkout_timeout: 1_000)
{:ok, true}

For long-running operations where you need to hold onto a worker (like maintaining a database connection for a TCP session), use acquire/2 and release/2:

iex> {:ok, worker} = Poolex.acquire(SomeWorker)
iex> # Use worker for as long as needed...
iex> GenServer.call(worker, :some_operation)
iex> Poolex.release(SomeWorker, worker)
:ok

Workers acquired with acquire/2 are automatically cleaned up if your process crashes, preventing resource leaks. The implementation is safe against double-release and ensures workers can only be released by their owner process.

A detailed description of the available configuration options and usage examples can be found in the documentation.

Guides

• Getting Started
  • Starting pool of workers
  • Poolex configuration options
  • Working with the pool
• Manual Worker Management
  • When to use acquire/release
  • Basic usage
  • Safety guarantees
  • Best practices
• Migration from :poolboy
• Example of use
  • Defining the worker
  • Configuring Poolex
  • Using Poolex
• Working with metrics
  • Pool size metrics
  • Integration with PromEx
• Workers and callers implementations
  • Callers
  • Workers
  • Writing custom implementations
• Controlling Pool Size with min_pool_size and max_pool_size
  • Setting an upper bound with max_pool_size
  • Setting a lower bound with min_pool_size
  • Using both options together
  • Partial execution
• Using worker_shutdown_delay for Overflow Workers
  • What are overflow workers?
  • The problem with immediate overflow worker shutdown
  • Solution: Delayed shutdown of overflow workers
  • Example usage
  • How it works
  • When to use
  • Default value

Used by

Contributions

If you think something can be improved or have any questions about specific behaviors or implementation details, please feel free to file an issue. Proposed changes should be discussed in issues before submitting any PRs, to avoid spending time on code that might not be merged upstream.

If you are ready to change the project, please read the Contributing guide first.

Support the Project

If you find Poolex useful, please consider supporting its development! You can:

• ⭐ Star the project on GitHub
• 💖 Sponsor the author on GitHub Sponsors

Your support helps keep the project active and maintained. Thank you!