ezpool

Generic connection pooling for Ruby. Originally forked from connection_pool, but with moderately different semantics.

MongoDB has its own connection pool. ActiveRecord has its own connection pool. This is a generic connection pool that can be used with anything, e.g. Redis, Dalli and other Ruby network clients.

Usage

Create a pool of objects to share amongst the fibers or threads in your Ruby application:

$memcached = EzPool.new(
  size: 5,
  timeout: 5,
  connect_with: proc { Dalli::Client.new }
)

You can also pass your connection function as a block:

$memcached = EzPool.new(size: 5, timeout: 5) { Dalli::Client.new }

Or you can configure it later:

$memcached = EzPool.new(size: 5, timeout: 5)
$memcached.connect_with { Dalli::Client.new }

Then use the pool in your application:

$memcached.with do |conn|
  conn.get('some-count')
end

If all the objects in the connection pool are in use, with will block until one becomes available. If no object is available within :timeout seconds, with will raise a Timeout::Error.

Optionally, you can specify a timeout override using the with-block semantics:

$memcached.with(timeout: 2.0) do |conn|
  conn.get('some-count')
end

This will only modify the resource-get timeout for this particular invocation. This is useful if you want to fail-fast on certain non critical sections when a resource is not available, or conversely if you are comfortable blocking longer on a particular resource. This is not implemented in the below EzPool::Wrapper class.

Note that you can also explicitly check-in/check-out connections using the #checkin and #checkout methods; however, there are no safety nets here! Once you check out a connection, nobody else may use it until you check it back in, and if you leak it, it's gone for good; we don't do anything clever like override the finalizer so that we can detect when the connection goes out of scope and return it to the pool. Caveat emptor!

Migrating to a Connection Pool

You can use EzPool::Wrapper to wrap a single global connection, making it easier to migrate existing connection code over time:

$redis = EzPool::Wrapper.new(size: 5, timeout: 3) { Redis.connect }
$redis.sadd('foo', 1)
$redis.smembers('foo')

The wrapper uses method_missing to checkout a connection, run the requested method and then immediately check the connection back into the pool. It's not high-performance so you'll want to port your performance sensitive code to use with as soon as possible.

$redis.with do |conn|
  conn.sadd('foo', 1)
  conn.smembers('foo')
end

And, of course, if there's any kind of load balancing or distribution on the other end of the connection, there is no guarantee that two subsequent calls to a Wrapper-wrapped object will go to the same database.

Once you've ported your entire system to use with, you can simply remove Wrapper and use the simpler and faster EzPool.

Thread-safety / Connection Multiplexing

EzPools are thread-safe and re-entrant in that the pool itself can be shared between different threads and it is guaranteed that the same connection will never be returned from overlapping calls to #checkout / #with. Note that this is achieved through the judicious use of mutexes; this code is not appropriate for systems with hard real-time requiremnts. Then again, neither is Ruby.

The original connection_pool library had special functionality so that if you checked out a connection from a thread which already had a checked out connection, you would be guaranteed to get the same connection back again. This logic prevents a number of valable use cases, so no longer exists. Each overlapping call to pool.checkout / pool.with will get a different connection.

In particular, this feature could be abused to assume that adjacent calls to Wraped connections from the same thread would go to the same database connection and perhaps the same session/transaction. Don't do that. If you care about transactions or database sessions, you need to be explicitly checking out and passing around connections.

Shutdown

You can shut down a EzPool instance once it should no longer be used. Further checkout attempts will immediately raise an error but existing checkouts will work.

cp = EzPool.new(
    connect_with: lambda { Redis.new },
    disconnect_with: lambda { |conn| conn.quit }
)
cp.shutdown

Shutting down a connection pool will block until all connections are checked in and closed. Note that shutting down is completely optional; Ruby's garbage collector will reclaim unreferenced pools under normal circumstances.

Connection recycling

If you specify the max_age parameter to a connection pool, it will attempt to gracefully recycle connections once they reach a certain age. This can be beneficial for, e.g., load balancers where you want client applications to eventually pick up new databases coming into service without having to explicitly restart the client processes.

Notes

• Connections are lazily created as needed.
• There is no provision for repairing or checking the health of a connection; connections should be self-repairing. This is true of the Dalli and Redis clients.
• WARNING: Don't ever use Timeout.timeout in your Ruby code or you will see occasional silent corruption and mysterious errors. The Timeout API is unsafe and cannot be used correctly, ever. Use proper socket timeout options as exposed by Net::HTTP, Redis, Dalli, etc.

Author

Originally by Mike Perham, @mperham, http://mikeperham.com

Forked and modified by engineers at EasyPost.