View Source Poolex (poolex v0.3.1)
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
Option | Description | Example | Default value |
---|---|---|---|
worker_module | Name of module that implements our worker | MyApp.Worker | option is required |
worker_start_fun | Name of the function that starts the worker | :run | :start |
worker_args | List of arguments passed to the start function | [:gg, "wp"] | [] |
workers_count | How many workers should be running in the pool | 5 | option 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
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
@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}
@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
@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
Option | Description | Example | Default value |
---|---|---|---|
worker_module | Name of module that implements our worker | MyApp.Worker | option is required |
worker_start_fun | Name of the function that starts the worker | :run | :start |
worker_args | List of arguments passed to the start function | [:gg, "wp"] | [] |
workers_count | How many workers should be running in the pool | 5 | option 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