edwardt / episcina

A simple non intrusive resource pool for connections

Episcina - A Simple Erlang Connection Pool

Episcina is designed as a pool for resources. Generally those resources are expected to be connections to some type of external thing like a sql system. However, there is nothing sql specific about episcina. You may generally consider it a small very focused pool implementation that does not try to take ownership of your work.

How It Works

Episcina will create any pools defined in the episcina's 'pools' environment parameter, which is a proplist that tells episcina how to connect. There are several parameters that are required.

• size - The maximum size of the pool
• timeout - The maximum number of milliseconds that the a caller is allowed to hold a connection. See below for the consequences of holding a connection open too long.
• connect_provider - This is the function + arguments that will be used to provide connections. It contains the name of the module, the name of the function and the arguments to pass to that function. There is an example below.
• close_provider - This is tthe function + arguments that will be used to close connections. It contains the name of the module, the name of the function and any arguments needed to be passed to that function. There is an example below.

Episcina also has two optional parameters:

• max_restarts: the number of restarts that are allowed to occur within max_seconds_between_restarts seconds. (Default: 1000)
• max_seconds_between_restarts: If more than max_restarts restarts occur within max_seconds_between_restarts seconds, the episcina supervisor will terminate all its child processes, then itself. (Default: 3600)

sys.config file example:

{episcina, [{max_restarts, 2000},
            {max_seconds_between_restarts, 7200},
            {pools, [{db1,
                          [{size, 10},
                           {timeout, 10000},
                           {connect_provider, {pgsql, connect,
                                               ["localhost",
                                                5432,
                                                "my supersecret pass",
                                                "postgresql",
                                                [{database, "foobar"}]]}},
                           {close_provider, {pgsql, close, []}}]}]}]}.

Pool Usage

{ok, C} = episcina:get_connection(Pool, Timeout).

• Pool - Name of pool.
• Timeout - Time, in milliseconds, to wait for a free connection.

ok = episcina:return_connection(Pool, Connection).

Details

• Episcina monitors the process which called get_connection and returns the allocated connection to the pool if that process dies.
• If a connection dies, a new one is created and added to the pool in its place.
• If the caller holds the pool longer the specified pool timeout then an exit message is sent to the calling process and the connection is returned to the pool.