View Source Poolex (poolex v0.7.0)
usage
Usage
In the most typical use of Poolex, you only need to start pool of workers as a child of your application.
children = [
Poolex.child_spec(
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)), timeout: 1_000)
{:ok, true}Fore more information see Getting Started
Link to this section Summary
Types
Tuple describing the caller.
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 |
| Option | Description | Example | Default value |
|---|---|---|---|
| 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.
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 caller() :: GenServer.from()
Tuple describing the caller.
Callers are processes that have requested to get a worker.
@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, pos_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()}
| 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 |
@type run_option() :: {:timeout, timeout()}
| Option | Description | Example | Default value |
|---|---|---|---|
| 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.
Link to this section Functions
@spec child_spec([poolex_option()]) :: Supervisor.child_spec()
Returns a specification to start this module under a supervisor.
options
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 |
examples
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.DebugInfo.t()
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.
* `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
Examples
iex> Poolex.start(pool_id: :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(pool_id: :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_busyif no free worker was found before the timeout.
See run!/3 for more information.
examples
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 -> 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(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)
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
Examples
iex> Poolex.start(pool_id: :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([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 |
|---|---|---|---|
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 |
examples
Examples
iex> Poolex.start_link(pool_id: :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