refactor kwarg handling, update documentation, no functional changes

Author: mperham

README.md

@@ -102,24 +102,15 @@ 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(idle_seconds: 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(idle_seconds: 300) { |conn| conn.close }
@@ -139,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
@@ -168,12 +159,11 @@ end
 cp.idle # => 1
 ```
 
-Upgrading from ConnectionPool 2
----------------------------------
+## Upgrading from ConnectionPool 2
 
-* Support for Rubies <3.2 has been removed.
+* Support for Ruby <3.2 has been removed.
 * ConnectionPool's APIs now consistently use keyword arguments everywhere.
-Any positional arguments must be converted to keywords:
+Positional arguments must be converted to keywords:
 ```ruby
 pool = ConnectionPool.new(size: 5, timeout: 5)
 pool.checkout(1) # 2.x
@@ -182,20 +172,15 @@ pool.checkout(timeout: 1) # 3.x
 pool.reap(idle_seconds: 30) # 3.x
 ```
 
-Notes
------
+## 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>

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 "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/timed_stack.rb

@@ -33,15 +33,15 @@ def initialize(size: 0, &block)
   end
 
   ##
-  # Returns +obj+ to the stack. +kwargs+ is ignored in TimedStack but may be
+  # Returns +obj+ to the stack. Additional kwargs are ignored in TimedStack but may be
   # used by subclasses that extend TimedStack.
-  def push(obj, **options)
+  def push(obj, **)
     @mutex.synchronize do
       if @shutdown_block
         @created -= 1 unless @created == 0
         @shutdown_block.call(obj)
       else
-        store_connection obj, **options
+        store_connection obj, **
       end
 
       @resource.broadcast
@@ -60,16 +60,16 @@ def push(obj, **options)
   #
   # The +timeout+ argument will be removed in 3.0.
   # Other options may be used by subclasses that extend TimedStack.
-  def pop(timeout: 0.5, exception: ConnectionPool::TimeoutError, **options)
+  def pop(timeout: 0.5, exception: ConnectionPool::TimeoutError, **)
     deadline = current_time + timeout
     @mutex.synchronize do
       loop do
         raise ConnectionPool::PoolShuttingDownError if @shutdown_block
-        if (conn = try_fetch_connection(**options))
+        if (conn = try_fetch_connection(**))
           return conn
         end
 
-        connection = try_create(**options)
+        connection = try_create(**)
         return connection if connection
 
         to_wait = deadline - current_time
@@ -104,21 +104,19 @@ def shutdown(reload: false, &block)
 
   ##
   # Reaps connections that were checked in more than +idle_seconds+ ago.
-  def reap(idle_seconds:, &block)
-    raise ArgumentError, "reap must receive a block" unless block
+  def reap(idle_seconds:, &)
+    raise ArgumentError, "reap must receive a block" unless block_given?
     raise ArgumentError, "idle_seconds must be a number" unless idle_seconds.is_a?(Numeric)
     raise ConnectionPool::PoolShuttingDownError if @shutdown_block
 
     idle.times do
-      conn =
-        @mutex.synchronize do
-          raise ConnectionPool::PoolShuttingDownError if @shutdown_block
-
-          reserve_idle_connection(idle_seconds)
-        end
+      conn = @mutex.synchronize do
+        raise ConnectionPool::PoolShuttingDownError if @shutdown_block
+        reserve_idle_connection(idle_seconds)
+      end
       break unless conn
 
-      block.call(conn)
+      yield conn
     end
   end
 
@@ -158,32 +156,32 @@ def current_time
   # This method must returns a connection from the stack if one exists. Allows
   # subclasses with expensive match/search algorithms to avoid double-handling
   # their stack.
-  def try_fetch_connection(**options)
-    connection_stored?(**options) && fetch_connection(**options)
+  def try_fetch_connection(**)
+    connection_stored?(**) && fetch_connection(**)
   end
 
   ##
   # This is an extension point for TimedStack and is called with a mutex.
   #
   # This method must returns true if a connection is available on the stack.
-  def connection_stored?(**options)
+  def connection_stored?(**)
     !@que.empty?
   end
 
   ##
   # This is an extension point for TimedStack and is called with a mutex.
   #
   # This method must return a connection from the stack.
-  def fetch_connection(**options)
+  def fetch_connection(**)
     @que.pop&.first
   end
 
   ##
   # This is an extension point for TimedStack and is called with a mutex.
   #
   # This method must shut down all connections on the stack.
-  def shutdown_connections(**options)
-    while (conn = try_fetch_connection(**options))
+  def shutdown_connections(**)
+    while (conn = try_fetch_connection(**))
       @created -= 1 unless @created == 0
       @shutdown_block.call(conn)
     end
@@ -214,7 +212,7 @@ def idle_connections?(idle_seconds)
   # This is an extension point for TimedStack and is called with a mutex.
   #
   # This method must return +obj+ to the stack.
-  def store_connection(obj, **options)
+  def store_connection(obj, **)
     @que.push [obj, current_time]
   end
 
@@ -223,7 +221,7 @@ def store_connection(obj, **options)
   #
   # This method must create a connection if and only if the total number of
   # connections allowed has not been met.
-  def try_create(**options)
+  def try_create(**)
     unless @created == @max
       object = @create_block.call
       @created += 1