connection_pool 2.4.1 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea0776fcb09a3cc48ef4ca03774399e20b09e51039d0c47c1e4cb3bac621c52b
-  data.tar.gz: b955d6b4e984259f20ae8cf6414f59692f9a51848424231363643e0c16dd2a3f
+  metadata.gz: 299b38ab20df15319b32d1a947b291137a5ab0f569d6ebf7153402f525f978c3
+  data.tar.gz: 300e5f15434761a80e388f5ff3a97e23d0a9d87d373e10703417231d6e14cf50
 SHA512:
-  metadata.gz: bf57d8b5547502d91f5550ca6ea0be16905604c90e61efb6741e5ec3ce607c7a65f0b31e1673c96c60a06a2f64f5239cab6e94d3a50095fb822ea9b1c1bb2f0a
-  data.tar.gz: 4b42aa5aa67b0e45bbbc8a9f29ca3a969efd8ade3b6dfca6cff082f526ec65a2a2e5c8fa17f512d33470b82535af8b675fc80903ccd75db26748e9845dd9a612
+  metadata.gz: 1ecdda6209d316a78ce8509514b4cb9676f5adae3cd07c95c75c9564b77a427d3c417e502aa32af65374f6aa63f8a5808b9ddf42d39ff89e9522adaf4c59dcd0
+  data.tar.gz: b1fb7ab8bc2cbcae36371268b03cdb59c4e25855cacd0d9588bfa012aea84801d4d879dff0a311492e89ba2584626029b85c1c3c9cf7efd51f8efb482c983f94

data/Changes.md

@@ -1,5 +1,16 @@
 # connection_pool Changelog
 
+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
 ------
 

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

@@ -41,6 +41,7 @@ class ConnectionPool::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
@@ -98,6 +99,26 @@ class ConnectionPool::TimedStack
     end
   end
 
+  ##
+  # 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.
 
@@ -112,6 +133,12 @@ class ConnectionPool::TimedStack
     @max - @created + @que.length
   end
 
+  ##
+  # The number of connections created and available on the stack.
+  def idle
+    @que.length
+  end
+
   private
 
   def current_time
@@ -133,7 +160,7 @@ class ConnectionPool::TimedStack
   # This method must return a connection from the stack.
 
   def fetch_connection(options = nil)
-    @que.pop
+    @que.pop&.first
   end
 
   ##
@@ -144,9 +171,32 @@ class ConnectionPool::TimedStack
   def shutdown_connections(options = nil)
     while connection_stored?(options)
       conn = 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 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
 
   ##
@@ -155,7 +205,7 @@ class ConnectionPool::TimedStack
   # This method must return +obj+ to the stack.
 
   def store_connection(obj, options = nil)
-    @que.push obj
+    @que.push [obj, current_time]
   end
 
   ##

data/lib/connection_pool/version.rb

@@ -1,3 +1,3 @@
 class ConnectionPool
-  VERSION = "2.4.1"
+  VERSION = "2.5.0"
 end

data/lib/connection_pool.rb

@@ -160,6 +160,12 @@ class ConnectionPool
     @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
@@ -169,6 +175,11 @@ class ConnectionPool
   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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: connection_pool
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.5.0
 platform: ruby
 authors:
 - Mike Perham
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-19 00:00:00.000000000 Z
+date: 2025-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -90,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.7
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Generic connection pool for Ruby