philiprehberger-pool

Generic thread-safe object pool with idle timeout and health checks

Requirements

Ruby >= 3.1

Installation

Add to your Gemfile:

gem "philiprehberger-pool"

Or install directly:

gem install philiprehberger-pool

Usage

require "philiprehberger/pool"

# Create a pool of database connections
pool = Philiprehberger::Pool.new(size: 5, timeout: 10) do
  SomeDatabase.connect(host: 'localhost')
end

# Automatic checkout/checkin with a block
pool.with do |conn|
  conn.query('SELECT 1')
end

# Manual checkout/checkin
conn = pool.checkout
begin
  conn.query('SELECT 1')
ensure
  pool.checkin(conn)
end

Health Checks

pool = Philiprehberger::Pool.new(
  size: 5,
  timeout: 10,
  health_check: ->(conn) { conn.ping }
) { SomeDatabase.connect }

Idle Timeout

pool = Philiprehberger::Pool.new(
  size: 5,
  idle_timeout: 60
) { SomeDatabase.connect }

Pool Stats

pool.stats
# => { size: 2, available: 1, in_use: 1, max: 5 }

Pruning Idle Resources

pool = Philiprehberger::Pool.new(size: 5, idle_timeout: 60) { TCPSocket.new("db.local", 5432) }

# Periodically reclaim idle handles without waiting for the next checkout
pruned = pool.prune_idle  # => count of resources evicted

Draining Idle Resources

require "philiprehberger/pool"

pool = Philiprehberger::Pool.new(size: 5) { TCPSocket.new("db.local", 5432) }

# Rotate connections after a config change
drained = pool.drain  # => closes idle connections, returns count
# New checkouts will create fresh connections

Shutdown

pool.shutdown
pool.shutdown? # => true

API

`Philiprehberger::Pool.new(size:, timeout: 5, idle_timeout: nil, health_check: nil, &factory)`

Creates a new resource pool.

Parameter	Description
`size`	Maximum number of resources
`timeout`	Seconds to wait for a resource (default: 5)
`idle_timeout`	Seconds before idle resources are evicted (default: nil)
`health_check`	Lambda called with resource, must return truthy (default: nil)
`&factory`	Block that creates a new resource

Instance Methods

Method	Description
`#with { \|resource\| ... }`	Checkout, yield, and auto-checkin
`#checkout(timeout: nil)`	Manually check out a resource
`#checkin(resource)`	Return a resource to the pool
`#drain`	Remove and close idle resources, return count drained
`#stats`	Hash with `:size`, `:available`, `:in_use`, `:max`
`#size`	Configured maximum capacity
`#prune_idle`	Evict available resources past `idle_timeout`, return count
`#shutdown`	Close all resources, reject new checkouts
`#shutdown?`	Whether the pool has been shut down

Errors

Error	Description
`Pool::TimeoutError`	Checkout timed out waiting for a resource
`Pool::ShutdownError`	Operation attempted on a shut-down pool

Development

bundle install
bundle exec rspec
bundle exec rubocop

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT