connection_pool 2.4.0 → 2.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e87682a6e57e8b0214de9c0713a7466a2b06399dc52d700fbf182cdf9e5b6606
-  data.tar.gz: d12337513b62d4677663403c512afad165275bdf848987182ce03637a1de6482
+  metadata.gz: ee1b7fff2f766c5941f36e0d62c07dd35c04864a19ecd7348d351e6b287bfb16
+  data.tar.gz: 3ec78e8d6b4763e26a73c5f865d92d0323ece85b85b858b28dc870da7babd640
 SHA512:
-  metadata.gz: eca2c1f8ebe52039f00df70ddfe5525cc0408acd8ae9849a8d1412bec670e7d3a05d3609db933e3e906cd83307d39f754dd5f1d7b48b50b847090b5bf485b55a
-  data.tar.gz: fc9a62b4b0ba5a406543e8f6399bd566f2f31c6c9a6ce2772e3550c1c2a75945c8a34defeda10c83e23cbfe5fe50d0e8861f57ea23935d7c97540aa97b04a635
+  metadata.gz: b656b3fed03027af31fa1b7e80574d8690669143f5a6496e0512d251a7aa8bf67393188e7b2a09855877fcb39f150cf9fad6b94d7b2dd974410af5791be24287
+  data.tar.gz: f5424045239ee1621049adcc37323ff182cc634303f41b46f150fdbf22ceed85d702bd116b74a8808f818e374bb262577852a5edd9233a1900857692f3ebc64c

data/Changes.md

@@ -1,5 +1,38 @@
 # connection_pool Changelog
 
+2.5.3
+------
+
+- Fix TruffleRuby/JRuby crash [#201]
+
+2.5.2
+------
+
+- Rollback inadvertant change to `auto_reload_after_fork` default. [#200]
+
+2.5.1
+------
+
+- Pass options to TimedStack in `checkout` [#195]
+- Optimize connection lookup [#196]
+- Fixes for use with Ractors
+
+2.5.0
+------
+
+- Reap idle connections [#187]
+```ruby
+idle_timeout = 60
+pool = ConnectionPool.new ...
+pool.reap(idle_timeout, &:close)
+```
+- `ConnectionPool#idle` returns the count of connections not in use [#187]
+
+2.4.1
+------
+
+- New `auto_reload_after_fork` config option to disable auto-drop [#177, shayonj]
+
 2.4.0
 ------
 

data/README.md

@@ -101,6 +101,34 @@ cp.with { |conn| conn.get('some-count') }
 
 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 specify how many seconds the connections have to be idle for them to be reaped.
+Defaults 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).
+Thread.new do
+  loop do
+    cp.reap(300) { |conn| conn.close }
+    sleep 300
+  end
+end
+```
+
 ## Current State
 
 There are several methods that return information about a pool.
@@ -109,11 +137,15 @@ There are several methods that return information about a pool.
 cp = ConnectionPool.new(size: 10) { Redis.new }
 cp.size # => 10
 cp.available # => 10
+cp.idle # => 0
 
 cp.with do |conn|
   cp.size # => 10
   cp.available # => 9
+  cp.idle # => 0
 end
+
+cp.idle # => 1
 ```
 
 Notes

data/connection_pool.gemspec

@@ -19,4 +19,6 @@ Gem::Specification.new do |s|
   s.add_development_dependency "minitest", ">= 5.0.0"
   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"}
 end

data/lib/connection_pool/timed_stack.rb

@@ -1,8 +1,8 @@
 ##
 # The TimedStack manages a pool of homogeneous connections (or any resource
-# you wish to manage).  Connections are created lazily up to a given maximum
+# you wish to manage). Connections are created lazily up to a given maximum
 # number.
-
+#
 # Examples:
 #
 #    ts = TimedStack.new(1) { MyConnection.new }
@@ -16,14 +16,12 @@
 #    conn = ts.pop
 #    ts.pop timeout: 5
 #    #=> raises ConnectionPool::TimeoutError after 5 seconds
-
 class ConnectionPool::TimedStack
   attr_reader :max
 
   ##
   # Creates a new pool with +size+ connections that are created from the given
   # +block+.
-
   def initialize(size = 0, &block)
     @create_block = block
     @created = 0
@@ -35,12 +33,12 @@ class ConnectionPool::TimedStack
   end
 
   ##
-  # Returns +obj+ to the stack.  +options+ is ignored in TimedStack but may be
+  # Returns +obj+ to the stack. +options+ is ignored in TimedStack but may be
   # used by subclasses that extend TimedStack.
-
   def push(obj, options = {})
     @mutex.synchronize do
       if @shutdown_block
+        @created -= 1 unless @created == 0
         @shutdown_block.call(obj)
       else
         store_connection obj, options
@@ -52,14 +50,13 @@ class ConnectionPool::TimedStack
   alias_method :<<, :push
 
   ##
-  # Retrieves a connection from the stack.  If a connection is available it is
-  # immediately returned.  If no connection is available within the given
+  # Retrieves a connection from the stack. If a connection is available it is
+  # immediately returned. If no connection is available within the given
   # timeout a ConnectionPool::TimeoutError is raised.
   #
   # +:timeout+ is the only checked entry in +options+ and is preferred over
-  # the +timeout+ argument (which will be removed in a future release).  Other
+  # the +timeout+ argument (which will be removed in a future release). Other
   # options may be used by subclasses that extend TimedStack.
-
   def pop(timeout = 0.5, options = {})
     options, timeout = timeout, 0.5 if Hash === timeout
     timeout = options.fetch :timeout, timeout
@@ -68,7 +65,9 @@ class ConnectionPool::TimedStack
     @mutex.synchronize do
       loop do
         raise ConnectionPool::PoolShuttingDownError if @shutdown_block
-        return fetch_connection(options) if connection_stored?(options)
+        if (conn = try_fetch_connection(options))
+          return conn
+        end
 
         connection = try_create(options)
         return connection if connection
@@ -85,7 +84,6 @@ class ConnectionPool::TimedStack
   # removing it from the pool. Attempting to checkout a connection after
   # shutdown will raise +ConnectionPool::PoolShuttingDownError+ unless
   # +:reload+ is +true+.
-
   def shutdown(reload: false, &block)
     raise ArgumentError, "shutdown must receive a block" unless block
 
@@ -99,19 +97,43 @@ class ConnectionPool::TimedStack
   end
 
   ##
-  # Returns +true+ if there are no available connections.
+  # 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
+    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
+      break unless conn
+
+      block.call(conn)
+    end
+  end
 
+  ##
+  # Returns +true+ if there are no available connections.
   def empty?
     (@created - @que.length) >= @max
   end
 
   ##
   # The number of connections available on the stack.
-
   def length
     @max - @created + @que.length
   end
 
+  ##
+  # The number of connections created and available on the stack.
+  def idle
+    @que.length
+  end
+
   private
 
   def current_time
@@ -121,8 +143,17 @@ class ConnectionPool::TimedStack
   ##
   # 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.
+  # 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 = nil)
+    connection_stored?(options) && fetch_connection(options)
+  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 = nil)
     !@que.empty?
   end
@@ -131,31 +162,48 @@ class ConnectionPool::TimedStack
   # 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 = nil)
-    @que.pop
+    @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 = nil)
-    while connection_stored?(options)
-      conn = fetch_connection(options)
+    while (conn = try_fetch_connection(options))
+      @created -= 1 unless @created == 0
       @shutdown_block.call(conn)
     end
-    @created = 0
   end
 
   ##
   # This is an extension point for TimedStack and is called with a mutex.
   #
-  # This method must return +obj+ to the stack.
+  # This method returns the oldest idle connection if it has been idle for more than idle_seconds.
+  # This requires that the stack is kept in order of checked in time (oldest first).
+  def reserve_idle_connection(idle_seconds)
+    return unless idle_connections?(idle_seconds)
+
+    @created -= 1 unless @created == 0
 
+    @que.shift.first
+  end
+
+  ##
+  # This is an extension point for TimedStack and is called with a mutex.
+  #
+  # Returns true if the first connection in the stack has been idle for more than idle_seconds
+  def idle_connections?(idle_seconds)
+    connection_stored? && (current_time - @que.first.last > idle_seconds)
+  end
+
+  ##
+  # 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 = nil)
-    @que.push obj
+    @que.push [obj, current_time]
   end
 
   ##
@@ -163,7 +211,6 @@ class ConnectionPool::TimedStack
   #
   # This method must create a connection if and only if the total number of
   # connections allowed has not been met.
-
   def try_create(options = nil)
     unless @created == @max
       object = @create_block.call

data/lib/connection_pool/version.rb

@@ -1,3 +1,3 @@
 class ConnectionPool
-  VERSION = "2.4.0"
+  VERSION = "2.5.3"
 end

data/lib/connection_pool.rb

@@ -36,9 +36,10 @@ end
 # Accepts the following options:
 # - :size - number of connections to pool, defaults to 5
 # - :timeout - amount of time to wait for a connection if none currently available, defaults to 5 seconds
+# - :auto_reload_after_fork - automatically drop all connections after fork, defaults to true
 #
 class ConnectionPool
-  DEFAULTS = {size: 5, timeout: 5}
+  DEFAULTS = {size: 5, timeout: 5, auto_reload_after_fork: true}.freeze
 
   def self.wrap(options, &block)
     Wrapper.new(options, &block)
@@ -50,11 +51,12 @@ class ConnectionPool
 
     def self.after_fork
       INSTANCES.values.each do |pool|
+        next unless pool.auto_reload_after_fork
+
         # We're on after fork, so we know all other threads are dead.
         # All we need to do is to ensure the main thread doesn't have a
         # checked out connection
         pool.checkin(force: true)
-
         pool.reload do |connection|
           # Unfortunately we don't know what method to call to close the connection,
           # so we try the most common one.
@@ -92,11 +94,12 @@ class ConnectionPool
 
     @size = Integer(options.fetch(:size))
     @timeout = options.fetch(:timeout)
+    @auto_reload_after_fork = options.fetch(:auto_reload_after_fork)
 
     @available = TimedStack.new(@size, &block)
     @key = :"pool-#{@available.object_id}"
     @key_count = :"pool-#{@available.object_id}-count"
-    INSTANCES[self] = self if INSTANCES
+    INSTANCES[self] = self if @auto_reload_after_fork && INSTANCES
   end
 
   def with(options = {})
@@ -119,7 +122,7 @@ class ConnectionPool
       ::Thread.current[@key]
     else
       ::Thread.current[@key_count] = 1
-      ::Thread.current[@key] = @available.pop(options[:timeout] || @timeout)
+      ::Thread.current[@key] = @available.pop(options[:timeout] || @timeout, options)
     end
   end
 
@@ -143,7 +146,6 @@ class ConnectionPool
   # Shuts down the ConnectionPool by passing each connection to +block+ and
   # then removing it from the pool. Attempting to checkout a connection after
   # shutdown will raise +ConnectionPool::PoolShuttingDownError+.
-
   def shutdown(&block)
     @available.shutdown(&block)
   end
@@ -152,18 +154,30 @@ class ConnectionPool
   # Reloads the ConnectionPool by passing each connection to +block+ and then
   # removing it the pool. Subsequent checkouts will create new connections as
   # needed.
-
   def reload(&block)
     @available.shutdown(reload: true, &block)
   end
 
+  ## 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)
+  end
+
   # Size of this connection pool
   attr_reader :size
+  # Automatically drop all connections after fork
+  attr_reader :auto_reload_after_fork
 
   # Number of pool entries available for checkout at this instant.
   def available
     @available.length
   end
+
+  # Number of pool entries created and idle in the pool.
+  def idle
+    @available.idle
+  end
 end
 
 require_relative "connection_pool/timed_stack"

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: connection_pool
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.5.3
 platform: ruby
 authors:
 - Mike Perham
 - Damian Janowski
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-24 00:00:00.000000000 Z
+date: 2025-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -72,8 +71,9 @@ files:
 homepage: https://github.com/mperham/connection_pool
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  changelog_uri: https://github.com/mperham/connection_pool/blob/main/Changes.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -88,8 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.7
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Generic connection pool for Ruby
 test_files: []