View Source Poolex (poolex v0.9.0)
Usage
In the most typical use of Poolex, you only need to start pool of workers as a child of your application.
children = [
{Poolex,
pool_id: :worker_pool,
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
:
Poolex.run(:worker_pool, &(is_pid?(&1)), checkout_timeout: 1_000)
{:ok, true}
Fore more information see Getting Started
Summary
Types
Any atom naming your pool, e.g. :my_pool
.
Option | Description | Example | Default value |
---|---|---|---|
pool_id | Identifier by which you will access the pool | :my_pool | option is required |
worker_module | Name of module that implements our worker | MyApp.Worker | option is required |
workers_count | How many workers should be running in the pool | 5 | option is required |
max_overflow | How many workers can be created over the limit | 2 | 0 |
worker_args | List of arguments passed to the start function | [:gg, "wp"] | [] |
worker_start_fun | Name of the function that starts the worker | :run | :start_link |
busy_workers_impl | Module that describes how to work with busy workers | SomeBusyWorkersImpl | Poolex.Workers.Impl.List |
idle_workers_impl | Module that describes how to work with idle workers | SomeIdleWorkersImpl | Poolex.Workers.Impl.List |
waiting_callers_impl | Module that describes how to work with callers queue | WaitingCallersImpl | Poolex.Callers.Impl.ErlangQueue |
pool_size_metrics | Whether to dispatch pool size metrics | true | false |
Option | Description | Example | Default value |
---|---|---|---|
checkout_timeout | How long we can wait for a worker on the call site | 60_000 | 5000 |
Process id of worker
.
Functions
Returns a specification to start this module under a supervisor.
Returns detailed information about started pool.
Returns current state of started pool.
The main function for working with the pool.
Starts a Poolex process without links (outside of a supervision tree).
Starts a Poolex process linked to the current process.
Types
@type pool_id() :: atom()
Any atom naming your pool, e.g. :my_pool
.
@type poolex_option() :: {:pool_id, pool_id()} | {:worker_module, module()} | {:workers_count, non_neg_integer()} | {:max_overflow, non_neg_integer()} | {:worker_args, [any()]} | {:worker_start_fun, atom()} | {:busy_workers_impl, module()} | {:idle_workers_impl, module()} | {:waiting_callers_impl, module()} | {:pool_size_metrics, boolean()}
Option | Description | Example | Default value |
---|---|---|---|
pool_id | Identifier by which you will access the pool | :my_pool | option is required |
worker_module | Name of module that implements our worker | MyApp.Worker | option is required |
workers_count | How many workers should be running in the pool | 5 | option is required |
max_overflow | How many workers can be created over the limit | 2 | 0 |
worker_args | List of arguments passed to the start function | [:gg, "wp"] | [] |
worker_start_fun | Name of the function that starts the worker | :run | :start_link |
busy_workers_impl | Module that describes how to work with busy workers | SomeBusyWorkersImpl | Poolex.Workers.Impl.List |
idle_workers_impl | Module that describes how to work with idle workers | SomeIdleWorkersImpl | Poolex.Workers.Impl.List |
waiting_callers_impl | Module that describes how to work with callers queue | WaitingCallersImpl | Poolex.Callers.Impl.ErlangQueue |
pool_size_metrics | Whether to dispatch pool size metrics | true | false |
@type run_option() :: {:checkout_timeout, timeout()}
Option | Description | Example | Default value |
---|---|---|---|
checkout_timeout | How long we can wait for a worker on the call site | 60_000 | 5000 |
@type worker() :: pid()
Process id of worker
.
Workers are processes launched in a pool.
Functions
@spec child_spec([poolex_option()]) :: Supervisor.child_spec()
Returns a specification to start this module under a supervisor.
Options
Option | Description | Example | Default value |
---|---|---|---|
pool_id | Identifier by which you will access the pool | :my_pool | option is required |
worker_module | Name of module that implements our worker | MyApp.Worker | option is required |
workers_count | How many workers should be running in the pool | 5 | option is required |
max_overflow | How many workers can be created over the limit | 2 | 0 |
worker_args | List of arguments passed to the start function | [:gg, "wp"] | [] |
worker_start_fun | Name of the function that starts the worker | :run | :start_link |
busy_workers_impl | Module that describes how to work with busy workers | SomeBusyWorkersImpl | Poolex.Workers.Impl.List |
idle_workers_impl | Module that describes how to work with idle workers | SomeIdleWorkersImpl | Poolex.Workers.Impl.List |
waiting_callers_impl | Module that describes how to work with callers queue | WaitingCallersImpl | Poolex.Callers.Impl.ErlangQueue |
pool_size_metrics | Whether to dispatch pool size metrics | true | false |
Examples
children = [
Poolex.child_spec(pool_id: :worker_pool_1, worker_module: SomeWorker, workers_count: 5),
# or in another way
{Poolex, [pool_id: :worker_pool_2, worker_module: SomeOtherWorker, workers_count: 5]}
]
Supervisor.start_link(children, strategy: :one_for_one)
@spec get_debug_info(pool_id()) :: Poolex.Private.DebugInfo.t()
Returns detailed information about started pool.
Primarily needed to help with debugging. Avoid using this function in production.
Fields
* `busy_workers_count` - how many workers are busy right now.
* `busy_workers_pids` - list of busy workers.
* `idle_workers_count` - how many workers are ready to work.
* `idle_workers_pids` - list of idle workers.
* `max_overflow` - how many workers can be created over the limit.
* `overflow` - current count of workers launched over limit.
* `waiting_caller_pids` - list of callers processes.
* `worker_args` - what parameters are used to start the worker.
* `worker_module` - name of a module that describes a worker.
* `worker_start_fun` - what function is used to start the worker.
Examples
iex> Poolex.start(pool_id: :my_pool_3, worker_module: Agent, worker_args: [fn -> 0 end], workers_count: 5)
iex> debug_info = %Poolex.Private.DebugInfo{} = Poolex.get_debug_info(:my_pool_3)
iex> debug_info.busy_workers_count
0
iex> debug_info.idle_workers_count
5
@spec get_state(pool_id()) :: Poolex.Private.State.t()
Returns current state of started pool.
Primarily needed to help with debugging. Avoid using this function in production.
Examples
iex> Poolex.start(pool_id: :my_pool_2, worker_module: Agent, worker_args: [fn -> 0 end], workers_count: 5)
iex> state = %Poolex.Private.State{} = Poolex.get_state(:my_pool_2)
iex> state.worker_module
Agent
iex> is_pid(state.supervisor)
true
@spec run(pool_id(), (worker :: pid() -> any()), [run_option()]) :: {:ok, any()} | {:error, :checkout_timeout}
The main function for working with the pool.
It takes a pool identifier, a function that takes a worker process id as an argument and returns any value.
When executed, an attempt is made to find a free worker with specified timeout (5 seconds by default).
You can set the timeout using the checkout_timeout
option.
Returns:
{:ok, result}
if the worker was found and the function was executed successfully.{:error, :checkout_timeout}
if no free worker was found before the timeout.
Examples
iex> Poolex.start_link(pool_id: :some_pool, worker_module: Agent, worker_args: [fn -> 5 end], workers_count: 1)
iex> Poolex.run(:some_pool, fn pid -> Agent.get(pid, &(&1)) end)
{:ok, 5}
@spec start([poolex_option()]) :: GenServer.on_start()
Starts a Poolex process without links (outside of a supervision tree).
See start_link/1 for more information.
Examples
iex> Poolex.start(pool_id: :my_pool, worker_module: Agent, worker_args: [fn -> 0 end], workers_count: 5)
iex> %Poolex.Private.State{worker_module: worker_module} = Poolex.get_state(:my_pool)
iex> worker_module
Agent
@spec start_link([poolex_option()]) :: GenServer.on_start()
Starts a Poolex process linked to the current process.
This is often used to start the Poolex as part of a supervision tree.
After the process is started, you can access it using the previously specified pool_id
.
Options
Option | Description | Example | Default value |
---|---|---|---|
pool_id | Identifier by which you will access the pool | :my_pool | option is required |
worker_module | Name of module that implements our worker | MyApp.Worker | option is required |
workers_count | How many workers should be running in the pool | 5 | option is required |
max_overflow | How many workers can be created over the limit | 2 | 0 |
worker_args | List of arguments passed to the start function | [:gg, "wp"] | [] |
worker_start_fun | Name of the function that starts the worker | :run | :start_link |
busy_workers_impl | Module that describes how to work with busy workers | SomeBusyWorkersImpl | Poolex.Workers.Impl.List |
idle_workers_impl | Module that describes how to work with idle workers | SomeIdleWorkersImpl | Poolex.Workers.Impl.List |
waiting_callers_impl | Module that describes how to work with callers queue | WaitingCallersImpl | Poolex.Callers.Impl.ErlangQueue |
pool_size_metrics | Whether to dispatch pool size metrics | true | false |
Examples
iex> Poolex.start_link(pool_id: :other_pool, worker_module: Agent, worker_args: [fn -> 0 end], workers_count: 5)
iex> %Poolex.Private.State{worker_module: worker_module} = Poolex.get_state(:other_pool)
iex> worker_module
Agent