View Source Poolex (poolex v0.3.0)

Getting Started

starting-pool-of-workers

Starting pool of workers

To start a cache you can use either start/2 or start_link/2. The first argument is the name of the pool and defines how you will communicate with it.

Poolex.start_link(:my_pool, worker_module: SomeWorker, workers_count: 10)

In general you should place it into your Supervision tree for fault tolerance.

pool_config = [
  worker_module: SomeWorker,
  workers_count: 10
]

children = [
  %{
    id: :my_pool,
    start: {Poolex, :start_link, [:my_pool, pool_config]}
  }
]

Supervisor.start_link(children, strategy: :one_for_one)

The second argument should contain a set of options for starting the pool.

poolex-configuration-options

Poolex configuration options

OptionDescriptionExampleDefault value
worker_moduleName of module that implements our workerMyApp.Workeroption is required
worker_start_funName of the function that starts the worker:run:start
worker_argsList of arguments passed to the start function[:gg, "wp"][]
workers_countHow many workers should be running in the pool5option is required

working-with-the-pool

Working with the pool

After the pool is initialized, you can get a free worker and perform any operations on it. This is done through the main interfaces run/3 and run!/3. The functions work the same and the only difference between them is that run/3 takes care of the runtime error handling.

The first argument is the name of the pool mentioned above.

The second argument is the function that takes the pid of the worker as the only parameter and performs the necessary actions.

The third argument contains run options. Currently there is only one timeout option that tells to Poolex how long we can to wait for a worker on the call side.

iex> Poolex.start_link(:agent_pool, worker_module: Agent, worker_args: [fn -> 5 end], workers_count: 1)
iex> Poolex.run(:agent_pool, fn pid -> Agent.get(pid, &(&1)) end)
{:ok, 5}
iex> Poolex.run!(:agent_pool, fn pid -> Agent.get(pid, &(&1)) end)
5

If you would like to see examples of using Poolex, then check out Example of Use.

Link to this section Summary

Functions

Returns a specification to start this module under a supervisor.

Returns detailed information about started pool.

Returns current state of started pool.

Same as run!/3 but handles runtime_errors.

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.

Link to this section Types

@type pool_id() :: atom()
@type poolex_option() ::
  {:worker_module, module()}
  | {:worker_start_fun, atom()}
  | {:worker_args, [any()]}
  | {:workers_count, pos_integer()}
@type run_option() :: {:timeout, timeout()}

Link to this section Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Returns detailed information about started pool.

Primarily needed to help with debugging. Avoid using this function in production.

fields

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.
* `worker_module` - name of a module that describes a worker.
* `worker_args` - what parameters are used to start the worker.
* `worker_start_fun` - what function is used to start the worker.
* `waiting_caller_pids` - list of callers processes.

examples

Examples

iex> Poolex.start(:my_pool, worker_module: Agent, worker_args: [fn -> 0 end], workers_count: 5)
iex> debug_info = %Poolex.DebugInfo{} = Poolex.get_debug_info(:my_pool)
iex> debug_info.busy_workers_count
0
iex> debug_info.idle_workers_count
5
@spec get_state(pool_id()) :: Poolex.State.t()

Returns current state of started pool.

Primarily needed to help with debugging. Avoid using this function in production.

examples

Examples

iex> Poolex.start(:my_pool, worker_module: Agent, worker_args: [fn -> 0 end], workers_count: 5)
iex> state = %Poolex.State{} = Poolex.get_state(:my_pool)
iex> state.worker_module
Agent
iex> is_pid(state.supervisor)
true
Link to this function

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

View Source
@spec run(pool_id(), (worker :: pid() -> any()), [run_option()]) ::
  {:ok, any()} | :all_workers_are_busy | {:runtime_error, any()}

Same as run!/3 but handles runtime_errors.

Returns:

  • {:runtime_error, reason} on errors.
  • :all_workers_are_busy if no free worker was found before the timeout.

See run!/3 for more information.

examples

Examples

iex> Poolex.start_link(:some_pool, worker_module: Agent, worker_args: [fn -> 5 end], workers_count: 1)
iex> Poolex.run(:some_pool, fn _pid -> raise RuntimeError end)
{:runtime_error, %RuntimeError{message: "runtime error"}}
iex> Poolex.run(:some_pool, fn pid -> Agent.get(pid, &(&1)) end)
{:ok, 5}
Link to this function

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

View Source
@spec run!(pool_id(), (worker :: pid() -> any()), [run_option()]) :: any()

The main function for working with the pool.

When executed, an attempt is made to obtain a worker with the specified timeout (5 seconds by default). In case of successful execution of the passed function, the result will be returned, otherwise an error will be raised.

examples

Examples

iex> Poolex.start_link(: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)
5
@spec start(pool_id(), [poolex_option()]) :: GenServer.on_start()

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

See start_link/2 for more information.

examples

Examples

iex> Poolex.start(:my_pool, worker_module: Agent, worker_args: [fn -> 0 end], workers_count: 5)
iex> %Poolex.State{worker_module: worker_module} = Poolex.get_state(:my_pool)
iex> worker_module
Agent
Link to this function

start_link(pool_id, opts)

View Source
@spec start_link(pool_id(), [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

Options

OptionDescriptionExampleDefault value
worker_moduleName of module that implements our workerMyApp.Workeroption is required
worker_start_funName of the function that starts the worker:run:start
worker_argsList of arguments passed to the start function[:gg, "wp"][]
workers_countHow many workers should be running in the pool5option is required

examples

Examples

iex> Poolex.start_link(:other_pool, worker_module: Agent, worker_args: [fn -> 0 end], workers_count: 5)
iex> %Poolex.State{worker_module: worker_module} = Poolex.get_state(:other_pool)
iex> worker_module
Agent