ppool

ppool is a lightweight worker pool for Erlang, originally published as didactic code in Learn You Some Erlang by Frédéric Trottier-Hébert.

Copyright (c) 2009 Frédéric Trottier-Hébert; available under the terms of the MIT Licence.

Contents: Overview, Installing, Quick start, API, Workers, Supervision, Queue, Caveats, Development.

Overview

This library is the "ppool" application from the chapter "Building applications with OTP" of the book Learn You Some Erlang for Great Good (link above). The code is kept close to the book's, and is small enough to read in one sitting: five modules, about 250 lines.

A pool has a name and a limit N. At most N workers run at once. A request to run a worker is either started immediately, refused, or (if you choose a queueing call) held in a first-in first-out queue until a running worker exits.

Structure of the supervision tree:

ppool (application)
  ppool_supersup   registered as `ppool'; one_for_one
    ppool_sup      one per pool; one_for_all
      ppool_serv   the pool server, registered under the pool name
      ppool_worker_sup   simple_one_for_one; parent of the workers
        worker, worker, ...

The pool server counts free slots, monitors every worker it started, and holds the queue. When a monitored worker goes down (for any reason) it starts the next queued request, or frees the slot if the queue is empty.

The public API is the module ppool. The other modules are internal.

Installing

ppool 1.3.0 is on hex.pm (https://hex.pm/packages/ppool). With rebar3:

{deps, [{ppool, "1.3.0"}]}.

or from git (the repository is at https://github.com/mk270/ppool):

{deps, [{ppool, {git, "https://github.com/mk270/ppool.git",
                 {branch, "master"}}}]}.

Add ppool to the applications list of your application, or start it yourself with application:ensure_all_started(ppool). It depends only on kernel and stdlib.

Quick start

1> ppool:start_pool(nagger, 2, {ppool_nagger, start_link, []}).
{ok,<0.35.0>}
2> ppool:run(nagger, ["finish the chapter!", 10000, 10, self()]).
{ok,<0.39.0>}

(Start the application first with application:start(ppool).) The example worker ppool_nagger lives in the test/ directory of this repository, so it is only available when working on ppool itself; it is a gen_server that sends {self(), Task} to the given pid every Delay ms, Max times (or forever if Max is infinity). After the call above, the shell receives that message ten times at ten second intervals.

API

All functions are in the module ppool. Pool names are atoms. In the examples below Pid values are of course different on each run.

start_pool(Name, Limit, {M, F, A})

Starts a pool. Name is an atom; it becomes the registered name of the pool server, so it must not be registered already by any process. Limit is an integer of at least 1. {M, F, A} says how to start a worker: each worker is started with apply(M, F, A ++ Args), where Args is the list given to run/2 and friends. So A holds the arguments common to all workers and Args the per-call ones.

Returns {ok, SupPid} (the pid of the pool's supervisor) or {error, Reason}.

1> ppool:start_pool(nagger, 2, {ppool_nagger, start_link, []}).
{ok,<0.87.0>}
2> ppool:start_pool(nagger, 2, {ppool_nagger, start_link, []}).
{error,{already_started,<0.87.0>}}

Error cases:

stop_pool(Name)

Stops the pool: its supervisor is shut down, which shuts down the pool server and all running workers (they are asked to stop, and killed if they do not stop within 5 seconds). The queue is discarded. Returns ok, or {error, not_found} if there is no such pool (so a second call returns {error, not_found}).

1> ppool:stop_pool(nagger).
ok
2> ppool:stop_pool(nagger).
{error,not_found}

Callers blocked in sync_queue/2 when the pool is stopped exit with reason shutdown.

run(Name, Args)

Starts a worker immediately if the pool has a free slot. Returns {ok, Pid} with the worker's pid, or the atom noalloc if the pool is full. Nothing is queued on noalloc. If the worker cannot be started it returns {error, Reason} (see below).

1> ppool:run(nagger, [hi, 100, 2, self()]).
{ok,<0.90.0>}
2> flush().
Shell got {<0.90.0>,hi}
Shell got {<0.90.0>,hi}
3> ppool:run(nagger, [a, infinity, infinity, self()]).
{ok,<0.94.0>}
4> ppool:run(nagger, [b, infinity, infinity, self()]).
{ok,<0.95.0>}
5> ppool:run(nagger, [c, 10, 1, self()]).
noalloc

Error cases: if no pool has that name the caller exits with {noproc, {gen_server, call, [Name, {run, Args}]}}. If the worker's start function fails (returns {error, Reason}, raises, or does not exist, for example because Args has the wrong length) the call returns {error, Reason}, a warning is logged, and no slot is used. The pool, its running workers and its queue are not affected.

1> ppool:run(nagger, [too, many, arguments, here, now]).
{error,{'EXIT',{undef,[{ppool_nagger,start_link,
                           [too,many,arguments,here,now],
                           []},
                       {supervisor,do_start_child_i,3,
                                   [{file,"supervisor.erl"},...]},
                       ...]}}}

The call has the default 5 second gen_server timeout.

async_queue(Name, Args)

Runs a worker as soon as there is a free slot: immediately if there is one, otherwise after waiting in the queue. Returns ok at once and never tells you the worker's pid.

1> ppool:async_queue(nagger, [q1, 10, 1, self()]).
ok

This is a cast, but the pool name is checked first: if no pool has that name the caller exits with {noproc, {gen_server, cast, [Name, {async, Args}]}}, as for run/2, rather than the request being lost silently. (A pool that dies just after the check still loses the request.) If the worker cannot be started, nobody is told: the request is dropped and a warning is logged by the pool server. A free slot is not used up by this.

sync_queue(Name, Args)

Like run/2, but when the pool is full the caller blocks, with no timeout, until its request reaches the front of the queue and a worker has been started for it. Returns {ok, Pid}, or {error, Reason} if the worker could not be started, as for run/2; the pool then goes on to the next queued request.

1> ppool:sync_queue(nagger, [q2, 10, 1, self()]).
{ok,<0.101.0>}      %% after a slot became free

Error cases: noproc exit if there is no such pool; if the pool server dies while you wait, you exit with the reason it died with (for example shutdown after stop_pool/1). Because the timeout is infinity, wrap the call in your own timeout if you need one, for instance by calling it from a spawned process.

status(Name)

Returns the state of the pool server as a raw record tuple {state, Limit, Sup, Refs, Queue, Name}, for debugging. Limit is the number of free slots (limit minus running workers), Sup the pid of the worker supervisor, Refs a gb_sets of monitor references and Queue a queue of waiting requests. This shape is not a stable interface. Exits with noproc if the pool does not exist.

1> ppool:status(nagger).
{state,0,<0.89.0>,{2,{#Ref<...>,nil,{#Ref<...>,nil,nil}}},
       {[[q1,10,1,<0.10.0>]],[]},
       nagger}

start/2 and stop/1

Application callbacks. Use application:start(ppool) instead.

Writing a worker

A worker is started by apply(M, F, A ++ Args) and the function must behave like an OTP start_link: it must start a process linked to the caller and return {ok, Pid}.

Why: the caller is the worker supervisor (ppool_worker_sup), which needs the link to supervise the process and to shut it down when the pool stops. The pool server additionally monitors the returned pid to learn when the worker is finished. Each worker's exit, normal or not, frees its slot.

What other return values do:

The example from test/ppool_nagger.erl:

start_link(Task, Delay, Max, SendTo) ->
    gen_server:start_link(?MODULE, {Task, Delay, Max, SendTo}, []).

A pool started with {ppool_nagger, start_link, []} calls it as ppool_nagger:start_link(Task, Delay, Max, SendTo) for ppool:run(Pool, [Task, Delay, Max, SendTo]). With A = [pre] the call would be start_link(pre, Task, Delay, ...):

1> ppool:start_pool(o, 1, {ppool_nagger, start_link, [pre]}).
2> ppool:run(o, [1, 2, self()]).     %% start_link(pre, 1, 2, Self)
{ok,<0.92.0>}

Workers are temporary: they are never restarted. Shutdown timeout is 5000 ms. If a worker traps exits it still gets a proper shutdown request when the pool is stopped.

Supervision and failures

Worker exits (normal or crash) are not restarted. The pool server sees the 'DOWN' message, then starts the next queued request or frees the slot. Tested by killing a running worker with exit(Pid, kill): a queued request started in its place and the pool's slot count stayed correct.

A worker that fails to start does not count as a failure of anything: it does not disturb the running workers, the queue, the pool server or the worker supervisor (tested with many consecutive failures of every kind, well beyond the supervisor's restart intensity).

If the pool server crashes (or is killed) its pool supervisor (one_for_all, at most 1 restart in 3 seconds) restarts everything in that pool. Consequences, verified:

If the pool supervisor itself fails (a second crash within 3 seconds exceeds its restart intensity) the top-level supervisor restarts it, again giving an empty pool. The top-level supervisor allows 6 restarts in 3 seconds. If it dies, the application stops and all pools go with it. Pools are not persistent: after a restart of the application there are no pools and you must call start_pool/3 again.

Pools are independent: a crash in one does not affect the others.

The queue

The queue is strictly first-in first-out, and sync_queue/2 and async_queue/2 requests share it. Checked with a pool of limit 1: a running worker, then async r1, sync r2, async r3 were started in that order r1, r2, r3.

A request is only taken from the queue when a worker goes down; the pool never reorders or expires entries. The queue is held in the pool server's memory and is unbounded: 100000 queued requests were accepted without trouble, and nothing limits it. There is no back-pressure on async_queue/2, and no way to cancel a queued request or inspect it other than status/1. run/2 never looks at the queue: it returns noalloc when the pool is full even if requests are queued.

Limits and caveats

Development

You need Erlang/OTP and rebar3.

rebar3 compile
rebar3 eunit       # 27 tests
rebar3 dialyzer
rebar3 edoc        # writes doc/index.html

The API documentation is generated from edoc comments in src/. The test suite starts the application and uses ppool_nagger.

Licence and attribution

MIT licence; see LICENSE.txt. The code derives from the ppool application of Learn You Some Erlang for Great Good by Frederic Trottier-Hebert (https://learnyousomeerlang.com/), chapter "Building applications with OTP".