Behaviours: application.
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).
mfa_spec() = {module(), atom(), list()}
Module, function and leading arguments of a worker's start function.
name() = atom()
The name of a pool; also the registered name of its pool server.
start_error() = {invalid_name, term()} | {invalid_limit, term()} | {invalid_mfa, term()} | {already_started, pid()} | term()
Reason of a failed start_pool/3; see there.
| async_queue/2 | Asks the pool to run a worker as soon as a slot is free, without waiting. |
| run/2 | Starts a worker now if the pool has a free slot. |
| start/2 | Application callback; starts the top-level supervisor. |
| start_pool/3 | Starts a pool called Name that runs at most Limit workers
at once. |
| status/1 | Returns the internal state record of the pool server as a
tuple, {state, Limit, Sup, Refs, Queue, Name}. |
| stop/1 | Application callback; does nothing. |
| stop_pool/1 | Stops 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/2 | Like run/2, but if the pool is full, waits (with no
timeout) in the pool's queue until a slot is free. |
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(Name, Args) -> Result
Name = name()Args = list()Result = {ok, pid() | undefined} | noalloc | {error, term()}
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(Type, StartArgs) -> Result
Type = normalStartArgs = term()Result = {ok, pid()} | ignore | {error, term()}
Application callback; starts the top-level supervisor.
Not for direct use: call application:start(ppool).
start_pool(Name, Limit, MFA) -> Result
Name = name()Limit = pos_integer()MFA = mfa_spec()Result = {ok, pid()} | {error, start_error()}
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.
{error, {invalid_name, Name}} if Name is not an atom;{error, {invalid_limit, Limit}} if Limit is not an integer
or is less than 1;{error, {invalid_mfa, MFA}} if MFA is not a tuple
{Module, Function, Args} with atoms Module and Function and a
list Args.{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.
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(State) -> Result
State = term()Result = ok
Application callback; does nothing.
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(Name, Args) -> Result
Name = name()Args = list()Result = {ok, pid() | undefined} | {error, term()}
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