connection_pool 2.5.0 → 2.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 299b38ab20df15319b32d1a947b291137a5ab0f569d6ebf7153402f525f978c3
-  data.tar.gz: 300e5f15434761a80e388f5ff3a97e23d0a9d87d373e10703417231d6e14cf50
+  metadata.gz: 24c74a1caa5e04827c47155b75e19805bcda4c329e28793309dfa95b5881c4bd
+  data.tar.gz: 23aadf2da494be8c3314039700606cd4e01b58d6cae1f45e3b7cdef57a98e7bd
 SHA512:
-  metadata.gz: 1ecdda6209d316a78ce8509514b4cb9676f5adae3cd07c95c75c9564b77a427d3c417e502aa32af65374f6aa63f8a5808b9ddf42d39ff89e9522adaf4c59dcd0
-  data.tar.gz: b1fb7ab8bc2cbcae36371268b03cdb59c4e25855cacd0d9588bfa012aea84801d4d879dff0a311492e89ba2584626029b85c1c3c9cf7efd51f8efb482c983f94
+  metadata.gz: 0f2385ddf4619ebc1bf9e2f202024b330c170ae2e4e7e63480be0f556242140af75eb3d272f6d262b2fc859625f0861c560af6a58c20bea3d69b005e2d248472
+  data.tar.gz: 0ac5103c69aa2e8226d2fa872714f9bd611b24ea171e91ce3d7a3c9be62b9887e24916cf4b6b1e5bc8c407349f87c3ea855c4659dbf5f3f137cd45738301d1a6

data/Changes.md

@@ -1,5 +1,33 @@
 # connection_pool Changelog
 
+2.5.5
+------
+
+- Support `ConnectionPool::TimedStack#pop(exception: false)` [#207]
+  to avoid using exceptions as control flow.
+
+2.5.4
+------
+
+- Add ability to remove a broken connection from the pool [#204, womblep]
+
+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
 ------
 

data/README.md

@@ -129,6 +129,27 @@ Thread.new do
 end
 ```
 
+## Discarding Connections
+
+You can discard connections in the ConnectionPool instance to remove connections that are broken and can't be restarted. 
+
+NOTE: the connection is not closed. It will just be removed from the pool so it won't be selected again.
+
+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
+```
+
 ## Current State
 
 There are several methods that return information about a pool.

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,9 +33,8 @@ 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
@@ -53,14 +50,16 @@ 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
-  # options may be used by subclasses that extend TimedStack.
-
+  # @option options [Float] :timeout (0.5) Wait this many seconds for an available entry
+  # @option options [Class] :exception (ConnectionPool::TimeoutError) Exception class to raise
+  #   if an entry was not available within the timeout period. Use `exception: false` to return nil.
+  #
+  # The +timeout+ argument will be removed in 3.0.
+  # 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
@@ -69,13 +68,22 @@ 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
 
         to_wait = deadline - current_time
-        raise ConnectionPool::TimeoutError, "Waited #{timeout} sec, #{length}/#{@max} available" if to_wait <= 0
+        if to_wait <= 0
+          exc = options.fetch(:exception, ConnectionPool::TimeoutError)
+          if exc
+            raise ConnectionPool::TimeoutError, "Waited #{timeout} sec, #{length}/#{@max} available"
+          else
+            return nil
+          end
+        end
         @resource.wait(@mutex, to_wait)
       end
     end
@@ -86,7 +94,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
 
@@ -121,14 +128,12 @@ class ConnectionPool::TimedStack
 
   ##
   # 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
@@ -139,6 +144,12 @@ class ConnectionPool::TimedStack
     @que.length
   end
 
+  ##
+  # Reduce the created count
+  def decrement_created
+    @created -= 1 unless @created == 0
+  end
+
   private
 
   def current_time
@@ -148,8 +159,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
@@ -158,7 +178,6 @@ 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&.first
   end
@@ -167,10 +186,8 @@ class ConnectionPool::TimedStack
   # 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
@@ -181,7 +198,6 @@ class ConnectionPool::TimedStack
   #
   # 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)
 
@@ -194,7 +210,6 @@ class ConnectionPool::TimedStack
   # 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
@@ -203,7 +218,6 @@ class ConnectionPool::TimedStack
   # 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, current_time]
   end
@@ -213,7 +227,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.5.0"
+  VERSION = "2.5.5"
 end

data/lib/connection_pool.rb

@@ -39,7 +39,7 @@ 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}
+  DEFAULTS = {size: 5, timeout: 5, auto_reload_after_fork: true}.freeze
 
   def self.wrap(options, &block)
     Wrapper.new(options, &block)
@@ -99,10 +99,14 @@ class ConnectionPool
     @available = TimedStack.new(@size, &block)
     @key = :"pool-#{@available.object_id}"
     @key_count = :"pool-#{@available.object_id}-count"
-    INSTANCES[self] = self if INSTANCES
+    @discard_key = :"pool-#{@available.object_id}-discard"
+    INSTANCES[self] = self if @auto_reload_after_fork && INSTANCES
   end
 
   def with(options = {})
+    # 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)
       begin
@@ -116,20 +120,65 @@ class ConnectionPool
   end
   alias_method :then, :with
 
+  ##
+  # Marks the current thread's checked-out connection for discard.
+  #
+  # When a connection is marked for discard, it will not be returned to the pool
+  # when checked in. Instead, the connection will be discarded.
+  # This is useful when a connection has become invalid or corrupted
+  # and should not be reused.
+  #
+  # Takes an optional block that will be called with the connection to be discarded.
+  # The block should perform any necessary clean-up on the connection.
+  #
+  # @yield [conn]
+  # @yieldparam conn [Object] The connection to be discarded.
+  # @yieldreturn [void]
+  #
+  #
+  # Note: This only affects the connection currently checked out by the calling thread.
+  # The connection will be discarded when +checkin+ is called.
+  #
+  # @return [void]
+  #
+  # @example
+  #   pool.with do |conn|
+  #     begin
+  #       conn.execute("SELECT 1")
+  #     rescue SomeConnectionError
+  #       pool.discard_current_connection  # Mark connection as bad
+  #       raise
+  #     end
+  #   end
+  def discard_current_connection(&block)
+    ::Thread.current[@discard_key] = block || proc { |conn| conn }
+  end
+
   def checkout(options = {})
     if ::Thread.current[@key]
       ::Thread.current[@key_count] += 1
       ::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
 
   def checkin(force: false)
     if ::Thread.current[@key]
       if ::Thread.current[@key_count] == 1 || force
-        @available.push(::Thread.current[@key])
+        if ::Thread.current[@discard_key]
+          begin
+            @available.decrement_created
+            ::Thread.current[@discard_key].call(::Thread.current[@key])
+          rescue
+            nil
+          ensure
+            ::Thread.current[@discard_key] = nil
+          end
+        else
+          @available.push(::Thread.current[@key])
+        end
         ::Thread.current[@key] = nil
         ::Thread.current[@key_count] = nil
       else
@@ -146,7 +195,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
@@ -155,7 +203,6 @@ 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

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: connection_pool
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.5.5
 platform: ruby
 authors:
 - Mike Perham
 - Damian Janowski
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -75,7 +74,6 @@ licenses:
 metadata:
   changelog_uri: https://github.com/mperham/connection_pool/blob/main/Changes.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -90,8 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Generic connection pool for Ruby
 test_files: []