Erlang poolboy notes

There isn’t much documentation on the great Poolboy worker pool factory. Here are some notes that will hopefully help to understand Poolboy a little bit better.

Notes on the usage

See https://github.com/devinus/poolboy for the original “documentation”. Many will know, but somehow I didn’t: The workers are idle in the pool. One takes them out of the pool and after the work is done, one puts them back in. It’s not like they’re – like I initially thought – working *in* the pool.

(Besides AFAIK checkout and checkin are the only things poolboy utilizes to know whether a worker is busy or not. So you better make sure the checkin is called at least sometime.)

% get a PID of a process that *is* checked in into the pool (=idle)
1> Worker = poolboy:checkout(PoolName).

% now the worker is "checked out" = out of the pool doing work
% => do the actual work here
2> gen_server:call(Worker, Request).

% when you're done => check the worker back in for future use
% you can do this in the worker itself by using the "self" function
3> poolboy:checkin(PoolName, Worker).

Blocking and non-blocking pool worker calls / asynchronous calls

Using “call” like the original usage example is a blocking call. No multicore fun & magic etc. there… For non-blocking consider using “cast” http://erlang.org/doc/man/gen_server.html#cast-2 In some cases it might be the best idea to let the worker do the checkin himself by utilizing the “self” function.

Blocking and non-blocking worker checkout

If you didn’t already do, checkout the source code of poolboy. There you can find – among other things – the full specs of the checkout function. Interestingly enough it has two more optional parameters blocking (default true) and timeout (default 5000).

1> Worker = poolboy:checkout(PoolName).
% returns PID in under 5 seconds or 

2> Worker = poolboy:checkout(PoolName, false).
% no waiting, either you have an idle worker for me or not.

3> Worker = poolboy:checkout(PoolName, true, 10000).
% like the first one but wait 10 secs instead of 5

(At first my idea was to make a merge request for the documentation but the documentation is so straight to the point (for those who basically know how to use it already 😉 ) I didn’t want to ruin that.)