View Source Poolex (poolex v1.0.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

Functions

add_idle_workers!(pool_id, workers_count)

Adds some idle workers to existing pool.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_debug_info(pool_id)

Returns detailed information about started pool.

get_state(pool_id)

Returns current state of started pool.

remove_idle_workers!(pool_id, workers_count)

Removes some idle workers from existing pool. If the number of workers to remove is greater than the number of idle workers, all idle workers will be removed.

run(pool_id, fun, options \\ [])

The main function for working with the pool.

start(opts)

Starts a Poolex process without links (outside of a supervision tree).

start_link(opts)

Starts a Poolex process linked to the current process.

Types

pool_id()

@type pool_id() :: GenServer.name()

Any valid GenServer's name. It may be an atom like :some_pool or a tuple {:via, Registry, {MyApp.Registry, "pool"} if you want to use Registry.

poolex_option()

@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`

run_option()

@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`

worker()

@type worker() :: pid()

Process id of worker.

Workers are processes launched in a pool.

Functions

add_idle_workers!(pool_id, workers_count)

@spec add_idle_workers!(pool_id(), pos_integer()) :: :ok | no_return()

Adds some idle workers to existing pool.

child_spec(init_arg)

@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)

get_debug_info(pool_id)

@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

get_state(pool_id)

@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

remove_idle_workers!(pool_id, workers_count)

@spec remove_idle_workers!(pool_id(), pos_integer()) :: :ok | no_return()

Removes some idle workers from existing pool. If the number of workers to remove is greater than the number of idle workers, all idle workers will be removed.

run(pool_id, fun, options \\ [])

@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}

start(opts)

@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

start_link(opts)

@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