Module ppool

Public API of the ppool worker pool library.

Behaviours: application.

Description

Public API of the ppool worker pool library.

This is the only module applications are expected to call. The other modules (ppool_serv, ppool_sup, ppool_supersup and ppool_worker_sup) are internal: they implement the supervision tree and the pool server and are documented for maintainers only.

Start the ppool application first (it starts the top-level supervisor, registered as ppool), then create named pools with start_pool/3 and run work in them with run/2, sync_queue/2 or async_queue/2.

A worker module must export a function which starts a process linked to its caller and returns {ok, Pid} (as start_link functions of gen_server, gen_statem etc. do).

Derived from the ppool application in "Learn You Some Erlang for Great Good" by Frederic Trottier-Hebert (MIT licence).

Data Types

mfa_spec()

mfa_spec() = {module(), atom(), list()}

Module, function and leading arguments of a worker's start function.

name()

name() = atom()

The name of a pool; also the registered name of its pool server.

start_error()

start_error() = {invalid_name, term()} | {invalid_limit, term()} | {invalid_mfa, term()} | {already_started, pid()} | term()

Reason of a failed start_pool/3; see there.

Function Index

async_queue/2Asks the pool to run a worker as soon as a slot is free, without waiting.
run/2Starts a worker now if the pool has a free slot.
start/2Application callback; starts the top-level supervisor.
start_pool/3Starts a pool called Name that runs at most Limit workers at once.
status/1Returns the internal state record of the pool server as a tuple, {state, Limit, Sup, Refs, Queue, Name}.
stop/1Application callback; does nothing.
stop_pool/1Stops the pool called Name, killing its running workers (after giving them time to shut down if they trap exits) and discarding anything queued.
sync_queue/2Like run/2, but if the pool is full, waits (with no timeout) in the pool's queue until a slot is free.

Function Details

async_queue/2

async_queue(Name, Args) -> Result

Asks the pool to run a worker as soon as a slot is free, without waiting. Returns ok immediately. Exits with noproc if there is no pool called Name, as run/2 does, so a mistyped name is not mistaken for success. The worker's pid is not reported. If the worker cannot be started the request is dropped and a warning is logged.

run/2

run(Name, Args) -> Result

Starts a worker now if the pool has a free slot. Returns {ok, Pid} with the worker's pid, or noalloc if the pool is full; nothing is queued in that case. Exits with noproc if there is no pool called Name. If the worker cannot be started (the start function returns {error, Reason}, raises, or does not exist for these arguments) returns {error, Reason}; the pool, its running workers and its queue are not affected, and no slot is used. (undefined as a pid is possible if the start function returns ignore.)

start/2

start(Type, StartArgs) -> Result

Application callback; starts the top-level supervisor. Not for direct use: call application:start(ppool).

start_pool/3

start_pool(Name, Limit, MFA) -> Result

Starts a pool called Name that runs at most Limit workers at once. Each worker is started by calling apply(M, F, A ++ Args) where {M, F, A} is the third argument and Args the list given to run/2, sync_queue/2 or async_queue/2.

The arguments are checked first, in this order, before anything is started, and the first failure is returned as an error: nothing is started or registered. Otherwise returns {ok, SupPid} with the pid of the pool's supervisor, or {error, Reason} from starting it. A Name that is already used by a pool gives {error, {already_started, Pid}}; a Name registered by some other process gives an error whose reason also contains {already_started, Pid}. Exits with noproc if the ppool application is not running.

status/1

status(Name) -> Result

Returns the internal state record of the pool server as a tuple, {state, Limit, Sup, Refs, Queue, Name}. Intended for debugging only; its shape is not a stable interface. Limit is the number of free slots. Exits with noproc if there is no pool.

stop/1

stop(State) -> Result

Application callback; does nothing.

stop_pool/1

stop_pool(Name) -> Result

Stops the pool called Name, killing its running workers (after giving them time to shut down if they trap exits) and discarding anything queued. Returns ok, or {error, not_found} if there is no such pool.

sync_queue/2

sync_queue(Name, Args) -> Result

Like run/2, but if the pool is full, waits (with no timeout) in the pool's queue until a slot is free. Returns {ok, Pid} once the worker has been started. Exits with noproc if there is no pool called Name, or with the reason the pool server dies if it goes away while the caller waits. If the worker cannot be started returns {error, Reason}, as run/2 does, and the next request in the queue is tried.


Generated by EDoc