Connection Pool 3.0

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ["2.5", "2.6", "2.7", "3.0", "3.1", "3.2", "3.3", "3.4", "jruby"]
+        ruby: ["3.2", "3.3", "3.4", "4.0", "jruby"]
         experimental: [false]
         include:
         - ruby: "truffleruby"

.standard.yml

@@ -1,3 +1,3 @@
-ruby_version: 2.5.0
+ruby_version: 3.2.0
 fix: true
 parallel: true

Changes.md

@@ -1,5 +1,13 @@
 # connection_pool Changelog
 
+3.0.0
+------
+
+- **BREAKING CHANGES** `ConnectionPool` and `ConnectionPool::TimedStack` now
+  use keyword arguments rather than positional arguments everywhere.
+  See README for upgrade notes.
+- Dropped support for Ruby <3.2.0
+
 2.5.5
 ------
 

README.md

@@ -50,7 +50,6 @@ 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 `ConnectionPool::Wrapper` class.
 
 ## Migrating to a Connection Pool
 
@@ -103,27 +102,18 @@ Like `shutdown`, this will block until all connections are checked in and closed
 
 ## Reap
 
-You can reap idle connections in the ConnectionPool instance to close connections that were created but have not been used for a certain amount of time. This can be useful to run periodically in a separate thread especially if keeping the connection open is resource intensive.
+You can call `reap` periodically on the ConnectionPool instance to close connections that were created but have not been used for a certain amount of time. This can be useful in environments where connections are expensive.
 
-You can specify how many seconds the connections have to be idle for them to be reaped.
-Defaults to 60 seconds.
+You can specify how many seconds the connections have to be idle for them to be reaped, defaulting to 60 seconds.
 
 ```ruby
 cp = ConnectionPool.new { Redis.new }
-cp.reap(300) { |conn| conn.close } # Reaps connections that have been idle for 300 seconds (5 minutes).
-```
-
-### Reaper Thread
 
-You can start your own reaper thread to reap idle connections in the ConnectionPool instance on a regular interval.
-
-```ruby
-cp = ConnectionPool.new { Redis.new }
-
-# Start a reaper thread to reap connections that have been idle for 300 seconds (5 minutes).
+# Start a reaper thread to reap connections that have been
+# idle more than 300 seconds (5 minutes)
 Thread.new do
   loop do
-    cp.reap(300) { |conn| conn.close }
+    cp.reap(idle_seconds: 300) { |conn| conn.close }
     sleep 300
   end
 end
@@ -140,14 +130,14 @@ It can only be done inside the block passed to `with` or `with_timeout`.
 Takes an optional block that will be executed with the connection.
 
 ```ruby
-   pool.with do |conn|
-     begin
-       conn.execute("SELECT 1")
-     rescue SomeConnectionError
-       pool.discard_current_connection  # remove the connection from the pool
-       raise
-     end
-   end
+pool.with do |conn|
+  begin
+    conn.execute("SELECT 1")
+  rescue SomeConnectionError
+    pool.discard_current_connection  # remove the connection from the pool
+    raise
+  end
+end
 ```
 
 ## Current State
@@ -169,20 +159,28 @@ end
 cp.idle # => 1
 ```
 
-Notes
------
+## Upgrading from ConnectionPool 2
+
+* Support for Ruby <3.2 has been removed.
+* ConnectionPool's APIs now consistently use keyword arguments everywhere.
+Positional arguments must be converted to keywords:
+```ruby
+pool = ConnectionPool.new(size: 5, timeout: 5)
+pool.checkout(1) # 2.x
+pool.reap(30)    # 2.x
+pool.checkout(timeout: 1) # 3.x
+pool.reap(idle_seconds: 30) # 3.x
+```
+
+## 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
+- **WARNING**: Avoid `Timeout.timeout` in your Ruby code or you can 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.
+  and dangerous to use. Use proper socket timeout options as exposed by
+  Net::HTTP, Redis, Dalli, etc.
 
 
-Author
-------
+## Author
 
-Mike Perham, [@getajobmike](https://twitter.com/getajobmike), <https://www.mikeperham.com>
+Mike Perham, [@getajobmike](https://ruby.social/@getajobmike), <https://www.mikeperham.com>

Rakefile

@@ -6,5 +6,5 @@ Rake::TestTask.new
 task default: [:"standard:fix", :test]
 
 task :bench do
-  require_relative "./test/benchmarks.rb"
+  require_relative "test/benchmarks"
 end

connection_pool.gemspec

@@ -15,10 +15,18 @@ Gem::Specification.new do |s|
   s.executables = []
   s.require_paths = ["lib"]
   s.license = "MIT"
+
+  s.required_ruby_version = ">= 3.2.0"
   s.add_development_dependency "bundler"
-  s.add_development_dependency "minitest", ">= 5.0.0"
+  s.add_development_dependency "maxitest"
   s.add_development_dependency "rake"
-  s.required_ruby_version = ">= 2.5.0"
 
-  s.metadata = {"changelog_uri" => "https://github.com/mperham/connection_pool/blob/main/Changes.md", "rubygems_mfa_required" => "true"}
+  s.metadata = {
+    "bug_tracker_uri" => "https://github.com/mperham/connection_pool/issues",
+    "documentation_uri" => "https://github.com/mperham/connection_pool/wiki",
+    "changelog_uri" => "https://github.com/mperham/connection_pool/blob/main/Changes.md",
+    "source_code_uri" => "https://github.com/mperham/connection_pool",
+    "homepage_uri" => "https://github.com/mperham/connection_pool",
+    "rubygems_mfa_required" => "true"
+  }
 end

lib/connection_pool.rb

@@ -39,10 +39,8 @@ class TimeoutError < ::Timeout::Error; end
 # - :auto_reload_after_fork - automatically drop all connections after fork, defaults to true
 #
 class ConnectionPool
-  DEFAULTS = {size: 5, timeout: 5, auto_reload_after_fork: true}.freeze
-
-  def self.wrap(options, &block)
-    Wrapper.new(options, &block)
+  def self.wrap(**, &)
+    Wrapper.new(**, &)
   end
 
   if Process.respond_to?(:fork)
@@ -66,19 +64,18 @@ def self.after_fork
       nil
     end
 
-    if ::Process.respond_to?(:_fork) # MRI 3.1+
-      module ForkTracker
-        def _fork
-          pid = super
-          if pid == 0
-            ConnectionPool.after_fork
-          end
-          pid
+    module ForkTracker
+      def _fork
+        pid = super
+        if pid == 0
+          ConnectionPool.after_fork
         end
+        pid
       end
-      Process.singleton_class.prepend(ForkTracker)
     end
+    Process.singleton_class.prepend(ForkTracker)
   else
+    # JRuby, et al
     INSTANCES = nil
     private_constant :INSTANCES
 
@@ -87,28 +84,26 @@ def self.after_fork
     end
   end
 
-  def initialize(options = {}, &block)
-    raise ArgumentError, "Connection pool requires a block" unless block
-
-    options = DEFAULTS.merge(options)
+  def initialize(timeout: 5, size: 5, auto_reload_after_fork: true, &)
+    raise ArgumentError, "Connection pool requires a block" unless block_given?
 
-    @size = Integer(options.fetch(:size))
-    @timeout = options.fetch(:timeout)
-    @auto_reload_after_fork = options.fetch(:auto_reload_after_fork)
+    @size = Integer(size)
+    @timeout = Float(timeout)
+    @auto_reload_after_fork = auto_reload_after_fork
 
-    @available = TimedStack.new(@size, &block)
+    @available = TimedStack.new(size: @size, &)
     @key = :"pool-#{@available.object_id}"
     @key_count = :"pool-#{@available.object_id}-count"
     @discard_key = :"pool-#{@available.object_id}-discard"
     INSTANCES[self] = self if @auto_reload_after_fork && INSTANCES
   end
 
-  def with(options = {})
+  def with(**)
     # We need to manage exception handling manually here in order
     # to work correctly with `Timeout.timeout` and `Thread#raise`.
     # Otherwise an interrupted Thread can leak connections.
     Thread.handle_interrupt(Exception => :never) do
-      conn = checkout(options)
+      conn = checkout(**)
       begin
         Thread.handle_interrupt(Exception => :immediate) do
           yield conn
@@ -154,13 +149,15 @@ def discard_current_connection(&block)
     ::Thread.current[@discard_key] = block || proc { |conn| conn }
   end
 
-  def checkout(options = {})
+  def checkout(**options)
     if ::Thread.current[@key]
       ::Thread.current[@key_count] += 1
       ::Thread.current[@key]
     else
+      conn = @available.pop(timeout: options.fetch(:timeout, @timeout), **options)
+      ::Thread.current[@key] = conn
       ::Thread.current[@key_count] = 1
-      ::Thread.current[@key] = @available.pop(options[:timeout] || @timeout, options)
+      conn
     end
   end
 
@@ -209,8 +206,8 @@ def reload(&block)
 
   ## Reaps idle connections that have been idle for over +idle_seconds+.
   # +idle_seconds+ defaults to 60.
-  def reap(idle_seconds = 60, &block)
-    @available.reap(idle_seconds, &block)
+  def reap(idle_seconds: 60, &block)
+    @available.reap(idle_seconds:, &block)
   end
 
   # Size of this connection pool