connection_pool 2.2.0 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 57159a2ea25da28e141dc80936a642134fbc9680
-  data.tar.gz: 7f534538909e40c117b84090a89b6f4fcd5ca8ee
+SHA256:
+  metadata.gz: ea0776fcb09a3cc48ef4ca03774399e20b09e51039d0c47c1e4cb3bac621c52b
+  data.tar.gz: b955d6b4e984259f20ae8cf6414f59692f9a51848424231363643e0c16dd2a3f
 SHA512:
-  metadata.gz: bb15e188af8037b01d59ab3728ee010033ab6c71cdd82ed6a8f4f59609c23791d9afdb8a9e31c755079cd1ce7c6e0ca20a7b43d2bd4b142b7ddacbd9b9ad94c3
-  data.tar.gz: 69e22e8e329f525fb875c2abe1090a35a63d035bb9337d9bd79604f46f1f1c3dbb92a83d6bf8d899388e8873cf04060c288bfef0e760e14b23a2fa12b1ffdf32
+  metadata.gz: bf57d8b5547502d91f5550ca6ea0be16905604c90e61efb6741e5ec3ce607c7a65f0b31e1673c96c60a06a2f64f5239cab6e94d3a50095fb822ea9b1c1bb2f0a
+  data.tar.gz: 4b42aa5aa67b0e45bbbc8a9f29ca3a969efd8ade3b6dfca6cff082f526ec65a2a2e5c8fa17f512d33470b82535af8b675fc80903ccd75db26748e9845dd9a612

data/Changes.md

@@ -1,5 +1,51 @@
-connection\_pool changelog
----------------------------
+# connection_pool Changelog
+
+2.4.1
+------
+
+- New `auto_reload_after_fork` config option to disable auto-drop [#177, shayonj]
+
+2.4.0
+------
+
+- Automatically drop all connections after fork [#166]
+
+2.3.0
+------
+
+- Minimum Ruby version is now 2.5.0
+- Add pool size to TimeoutError message
+
+2.2.5
+------
+
+- Fix argument forwarding on Ruby 2.7 [#149]
+
+2.2.4
+------
+
+- Add `reload` to close all connections, recreating them afterwards [Andrew Marshall, #140]
+- Add `then` as a way to use a pool or a bare connection with the same code path [#138]
+
+2.2.3
+------
+
+- Pool now throws `ConnectionPool::TimeoutError` on timeout. [#130]
+- Use monotonic clock present in all modern Rubies [Tero Tasanen, #109]
+- Remove code hacks necessary for JRuby 1.7
+- Expose wrapped pool from ConnectionPool::Wrapper [Thomas Lecavelier, #113]
+
+2.2.2
+------
+
+- Add pool `size` and `available` accessors for metrics and monitoring
+  purposes [#97, robholland]
+
+2.2.1
+------
+
+- Allow CP::Wrapper to use an existing pool [#87, etiennebarrie]
+- Use monotonic time for more accurate timeouts [#84, jdantonio]
 
 2.2.0
 ------

data/README.md

@@ -1,24 +1,17 @@
 connection\_pool
 =================
-[![Build Status](https://travis-ci.org/mperham/connection_pool.svg)](https://travis-ci.org/mperham/connection_pool)
+[![Build Status](https://github.com/mperham/connection_pool/actions/workflows/ci.yml/badge.svg)](https://github.com/mperham/connection_pool/actions/workflows/ci.yml)
 
 Generic connection pooling for Ruby.
 
-MongoDB has its own connection pool.  ActiveRecord has its own connection pool.
-This is a generic connection pool that can be used with anything, e.g. Redis,
-Dalli and other Ruby network clients.
-
-**WARNING**: Don't ever use `Timeout.timeout` in your Ruby code or you will 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.
-
+MongoDB has its own connection pool.
+ActiveRecord has its own connection pool.
+This is a generic connection pool that can be used with anything, e.g. Redis, Dalli and other Ruby network clients.
 
 Usage
 -----
 
-Create a pool of objects to share amongst the fibers or threads in your Ruby
-application:
+Create a pool of objects to share amongst the fibers or threads in your Ruby application:
 
 ``` ruby
 $memcached = ConnectionPool.new(size: 5, timeout: 5) { Dalli::Client.new }
@@ -33,8 +26,17 @@ end
 ```
 
 If all the objects in the connection pool are in use, `with` will block
-until one becomes available.  If no object is available within `:timeout` seconds,
-`with` will raise a `Timeout::Error`.
+until one becomes available.
+If no object is available within `:timeout` seconds,
+`with` will raise a `ConnectionPool::TimeoutError` (a subclass of `Timeout::Error`).
+
+You can also use `ConnectionPool#then` to support _both_ a
+connection pool and a raw client.
+
+```ruby
+# Compatible with a raw Redis::Client, and ConnectionPool Redis
+$redis.then { |r| r.set 'foo' 'bar' }
+```
 
 Optionally, you can specify a timeout override using the with-block semantics:
 
@@ -45,24 +47,23 @@ end
 ```
 
 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 below
-`ConnectionPool::Wrapper` class.
+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
 
-You can use `ConnectionPool::Wrapper` to wrap a single global connection,
-making it easier to port your connection code over time:
+You can use `ConnectionPool::Wrapper` to wrap a single global connection, making it easier to migrate existing connection code over time:
 
 ``` ruby
-$redis = ConnectionPool::Wrapper.new(size: 5, timeout: 3) { Redis.connect }
+$redis = ConnectionPool::Wrapper.new(size: 5, timeout: 3) { Redis.new }
 $redis.sadd('foo', 1)
 $redis.smembers('foo')
 ```
 
-The wrapper uses `method_missing` to checkout a connection, run the requested
-method and then immediately check the connection back into the pool.  It's
-**not** high-performance so you'll want to port your performance sensitive code
-to use `with` as soon as possible.
+The wrapper uses `method_missing` to checkout a connection, run the requested method and then immediately check the connection back into the pool.
+It's **not** high-performance so you'll want to port your performance sensitive code to use `with` as soon as possible.
 
 ``` ruby
 $redis.with do |conn|
@@ -71,41 +72,64 @@ $redis.with do |conn|
 end
 ```
 
-Once you've ported your entire system to use `with`, you can simply remove
-`Wrapper` and use the simpler and faster `ConnectionPool`.
+Once you've ported your entire system to use `with`, you can simply remove `Wrapper` and use the simpler and faster `ConnectionPool`.
+
+
+## Shutdown
 
 You can shut down a ConnectionPool instance once it should no longer be used.
-Further checkout attempts will immediately raise an error but existing checkouts
-will work.
+Further checkout attempts will immediately raise an error but existing checkouts will work.
 
 ```ruby
 cp = ConnectionPool.new { Redis.new }
-cp.shutdown { |conn| conn.close }
+cp.shutdown { |c| c.close }
 ```
 
 Shutting down a connection pool will block until all connections are checked in and closed.
-Note that shutting down is completely optional; Ruby's garbage collector will reclaim
-unreferenced pools under normal circumstances.
+**Note that shutting down is completely optional**; Ruby's garbage collector will reclaim unreferenced pools under normal circumstances.
+
+## Reload
+
+You can reload a ConnectionPool instance in the case it is desired to close all connections to the pool and, unlike `shutdown`, afterwards recreate connections so the pool may continue to be used.
+Reloading may be useful after forking the process.
 
+```ruby
+cp = ConnectionPool.new { Redis.new }
+cp.reload { |conn| conn.quit }
+cp.with { |conn| conn.get('some-count') }
+```
+
+Like `shutdown`, this will block until all connections are checked in and closed.
+
+## Current State
+
+There are several methods that return information about a pool.
+
+```ruby
+cp = ConnectionPool.new(size: 10) { Redis.new }
+cp.size # => 10
+cp.available # => 10
+
+cp.with do |conn|
+  cp.size # => 10
+  cp.available # => 9
+end
+```
 
 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
+  connections should be self-repairing. This is true of the Dalli and Redis
   clients.
-
-
-Install
--------
-
-```
-$ gem install connection_pool
-```
+- **WARNING**: Don't ever use `Timeout.timeout` in your Ruby code or you will 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.
 
 
 Author
 ------
 
-Mike Perham, [@mperham](https://twitter.com/mperham), <http://mikeperham.com>
+Mike Perham, [@getajobmike](https://twitter.com/getajobmike), <https://www.mikeperham.com>

data/connection_pool.gemspec

@@ -1,21 +1,24 @@
-# -*- encoding: utf-8 -*-
 require "./lib/connection_pool/version"
 
 Gem::Specification.new do |s|
-  s.name        = "connection_pool"
-  s.version     = ConnectionPool::VERSION
-  s.platform    = Gem::Platform::RUBY
-  s.authors     = ["Mike Perham", "Damian Janowski"]
-  s.email       = ["mperham@gmail.com", "damian@educabilia.com"]
-  s.homepage    = "https://github.com/mperham/connection_pool"
-  s.description = s.summary = %q{Generic connection pool for Ruby}
+  s.name = "connection_pool"
+  s.version = ConnectionPool::VERSION
+  s.platform = Gem::Platform::RUBY
+  s.authors = ["Mike Perham", "Damian Janowski"]
+  s.email = ["mperham@gmail.com", "damian@educabilia.com"]
+  s.homepage = "https://github.com/mperham/connection_pool"
+  s.description = s.summary = "Generic connection pool for Ruby"
 
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.files = ["Changes.md", "LICENSE", "README.md", "connection_pool.gemspec",
+    "lib/connection_pool.rb", "lib/connection_pool/timed_stack.rb",
+    "lib/connection_pool/version.rb", "lib/connection_pool/wrapper.rb"]
+  s.executables = []
   s.require_paths = ["lib"]
   s.license = "MIT"
-  s.add_development_dependency 'bundler'
-  s.add_development_dependency 'minitest', '>= 5.0.0'
-  s.add_development_dependency 'rake'
+  s.add_development_dependency "bundler"
+  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,12 +1,3 @@
-require 'thread'
-require 'timeout'
-
-##
-# Raised when you attempt to retrieve a connection from a pool that has been
-# shut down.
-
-class ConnectionPool::PoolShuttingDownError < RuntimeError; end
-
 ##
 # The TimedStack manages a pool of homogeneous connections (or any resource
 # you wish to manage).  Connections are created lazily up to a given maximum
@@ -24,9 +15,10 @@ class ConnectionPool::PoolShuttingDownError < RuntimeError; end
 #
 #    conn = ts.pop
 #    ts.pop timeout: 5
-#    #=> raises Timeout::Error after 5 seconds
+#    #=> 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
@@ -37,8 +29,8 @@ class ConnectionPool::TimedStack
     @created = 0
     @que = []
     @max = size
-    @mutex = Mutex.new
-    @resource = ConditionVariable.new
+    @mutex = Thread::Mutex.new
+    @resource = Thread::ConditionVariable.new
     @shutdown_block = nil
   end
 
@@ -62,7 +54,7 @@ class ConnectionPool::TimedStack
   ##
   # 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 Timeout::Error is raised.
+  # 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
@@ -72,7 +64,7 @@ class ConnectionPool::TimedStack
     options, timeout = timeout, 0.5 if Hash === timeout
     timeout = options.fetch :timeout, timeout
 
-    deadline = Time.now + timeout
+    deadline = current_time + timeout
     @mutex.synchronize do
       loop do
         raise ConnectionPool::PoolShuttingDownError if @shutdown_block
@@ -81,25 +73,28 @@ class ConnectionPool::TimedStack
         connection = try_create(options)
         return connection if connection
 
-        to_wait = deadline - Time.now
-        raise Timeout::Error, "Waited #{timeout} sec" if to_wait <= 0
+        to_wait = deadline - current_time
+        raise ConnectionPool::TimeoutError, "Waited #{timeout} sec, #{length}/#{@max} available" if to_wait <= 0
         @resource.wait(@mutex, to_wait)
       end
     end
   end
 
   ##
-  # Shuts down the TimedStack which prevents connections from being checked
-  # out.  The +block+ is called once for each connection on the stack.
+  # Shuts down the TimedStack by passing each connection to +block+ and then
+  # removing it from the pool. Attempting to checkout a connection after
+  # shutdown will raise +ConnectionPool::PoolShuttingDownError+ unless
+  # +:reload+ is +true+.
 
-  def shutdown(&block)
-    raise ArgumentError, "shutdown must receive a block" unless block_given?
+  def shutdown(reload: false, &block)
+    raise ArgumentError, "shutdown must receive a block" unless block
 
     @mutex.synchronize do
       @shutdown_block = block
       @resource.broadcast
 
       shutdown_connections
+      @shutdown_block = nil if reload
     end
   end
 
@@ -119,6 +114,10 @@ class ConnectionPool::TimedStack
 
   private
 
+  def current_time
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
   ##
   # This is an extension point for TimedStack and is called with a mutex.
   #
@@ -147,6 +146,7 @@ class ConnectionPool::TimedStack
       conn = fetch_connection(options)
       @shutdown_block.call(conn)
     end
+    @created = 0
   end
 
   ##

data/lib/connection_pool/version.rb

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

data/lib/connection_pool/wrapper.rb

@@ -0,0 +1,56 @@
+class ConnectionPool
+  class Wrapper < ::BasicObject
+    METHODS = [:with, :pool_shutdown, :wrapped_pool]
+
+    def initialize(options = {}, &block)
+      @pool = options.fetch(:pool) { ::ConnectionPool.new(options, &block) }
+    end
+
+    def wrapped_pool
+      @pool
+    end
+
+    def with(&block)
+      @pool.with(&block)
+    end
+
+    def pool_shutdown(&block)
+      @pool.shutdown(&block)
+    end
+
+    def pool_size
+      @pool.size
+    end
+
+    def pool_available
+      @pool.available
+    end
+
+    def respond_to?(id, *args)
+      METHODS.include?(id) || with { |c| c.respond_to?(id, *args) }
+    end
+
+    # rubocop:disable Style/MissingRespondToMissing
+    if ::RUBY_VERSION >= "3.0.0"
+      def method_missing(name, *args, **kwargs, &block)
+        with do |connection|
+          connection.send(name, *args, **kwargs, &block)
+        end
+      end
+    elsif ::RUBY_VERSION >= "2.7.0"
+      ruby2_keywords def method_missing(name, *args, &block)
+        with do |connection|
+          connection.send(name, *args, &block)
+        end
+      end
+    else
+      def method_missing(name, *args, &block)
+        with do |connection|
+          connection.send(name, *args, &block)
+        end
+      end
+    end
+    # rubocop:enable Style/MethodMissingSuper
+    # rubocop:enable Style/MissingRespondToMissing
+  end
+end

data/lib/connection_pool.rb

@@ -1,21 +1,27 @@
-require_relative 'connection_pool/version'
-require_relative 'connection_pool/timed_stack'
+require "timeout"
+require_relative "connection_pool/version"
 
+class ConnectionPool
+  class Error < ::RuntimeError; end
+
+  class PoolShuttingDownError < ::ConnectionPool::Error; end
+
+  class TimeoutError < ::Timeout::Error; end
+end
 
-# Generic connection pool class for e.g. sharing a limited number of network connections
-# among many threads.  Note: Connections are lazily created.
+# Generic connection pool class for sharing a limited number of objects or network connections
+# among many threads.  Note: pool elements are lazily created.
 #
 # Example usage with block (faster):
 #
 #    @pool = ConnectionPool.new { Redis.new }
-#
 #    @pool.with do |redis|
 #      redis.lpop('my-list') if redis.llen('my-list') > 0
 #    end
 #
 # Using optional timeout override (for that single invocation)
 #
-#    @pool.with(:timeout => 2.0) do |redis|
+#    @pool.with(timeout: 2.0) do |redis|
 #      redis.lpop('my-list') if redis.llen('my-list') > 0
 #    end
 #
@@ -30,32 +36,72 @@ require_relative 'connection_pool/timed_stack'
 # 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}
-
-  class Error < RuntimeError
-  end
+  DEFAULTS = {size: 5, timeout: 5, auto_reload_after_fork: true}
 
   def self.wrap(options, &block)
     Wrapper.new(options, &block)
   end
 
+  if Process.respond_to?(:fork)
+    INSTANCES = ObjectSpace::WeakMap.new
+    private_constant :INSTANCES
+
+    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.
+          connection.close if connection.respond_to?(:close)
+        end
+      end
+      nil
+    end
+
+    if ::Process.respond_to?(:_fork) # MRI 3.1+
+      module ForkTracker
+        def _fork
+          pid = super
+          if pid == 0
+            ConnectionPool.after_fork
+          end
+          pid
+        end
+      end
+      Process.singleton_class.prepend(ForkTracker)
+    end
+  else
+    INSTANCES = nil
+    private_constant :INSTANCES
+
+    def self.after_fork
+      # noop
+    end
+  end
+
   def initialize(options = {}, &block)
-    raise ArgumentError, 'Connection pool requires a block' unless block
+    raise ArgumentError, "Connection pool requires a block" unless block
 
     options = DEFAULTS.merge(options)
 
-    @size = options.fetch(:size)
+    @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 = :"current-#{@available.object_id}"
+    @key = :"pool-#{@available.object_id}"
+    @key_count = :"pool-#{@available.object_id}-count"
+    INSTANCES[self] = self if INSTANCES
   end
 
-if Thread.respond_to?(:handle_interrupt)
-
-  # MRI
   def with(options = {})
     Thread.handle_interrupt(Exception => :never) do
       conn = checkout(options)
@@ -68,81 +114,62 @@ if Thread.respond_to?(:handle_interrupt)
       end
     end
   end
-
-else
-
-  # jruby 1.7.x
-  def with(options = {})
-    conn = checkout(options)
-    begin
-      yield conn
-    ensure
-      checkin
-    end
-  end
-
-end
+  alias_method :then, :with
 
   def checkout(options = {})
-    conn = if stack.empty?
-      timeout = options[:timeout] || @timeout
-      @available.pop(timeout: timeout)
+    if ::Thread.current[@key]
+      ::Thread.current[@key_count] += 1
+      ::Thread.current[@key]
     else
-      stack.last
+      ::Thread.current[@key_count] = 1
+      ::Thread.current[@key] = @available.pop(options[:timeout] || @timeout)
     end
-
-    stack.push conn
-    conn
   end
 
-  def checkin
-    conn = pop_connection # mutates stack, must be on its own line
-    @available.push(conn) if stack.empty?
+  def checkin(force: false)
+    if ::Thread.current[@key]
+      if ::Thread.current[@key_count] == 1 || force
+        @available.push(::Thread.current[@key])
+        ::Thread.current[@key] = nil
+        ::Thread.current[@key_count] = nil
+      else
+        ::Thread.current[@key_count] -= 1
+      end
+    elsif !force
+      raise ConnectionPool::Error, "no connections are checked out"
+    end
 
     nil
   end
 
+  ##
+  # 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
 
-  private
-
-  def pop_connection
-    if stack.empty?
-      raise ConnectionPool::Error, 'no connections are checked out'
-    else
-      stack.pop
-    end
-  end
+  ##
+  # Reloads the ConnectionPool by passing each connection to +block+ and then
+  # removing it the pool. Subsequent checkouts will create new connections as
+  # needed.
 
-  def stack
-    ::Thread.current[@key] ||= []
+  def reload(&block)
+    @available.shutdown(reload: true, &block)
   end
 
-  class Wrapper < ::BasicObject
-    METHODS = [:with, :pool_shutdown]
+  # Size of this connection pool
+  attr_reader :size
+  # Automatically drop all connections after fork
+  attr_reader :auto_reload_after_fork
 
-    def initialize(options = {}, &block)
-      @pool = ::ConnectionPool.new(options, &block)
-    end
-
-    def with(&block)
-      @pool.with(&block)
-    end
-
-    def pool_shutdown(&block)
-      @pool.shutdown(&block)
-    end
-
-    def respond_to?(id, *args)
-      METHODS.include?(id) || with { |c| c.respond_to?(id, *args) }
-    end
-
-    def method_missing(name, *args, &block)
-      with do |connection|
-        connection.send(name, *args, &block)
-      end
-    end
+  # Number of pool entries available for checkout at this instant.
+  def available
+    @available.length
   end
 end
+
+require_relative "connection_pool/timed_stack"
+require_relative "connection_pool/wrapper"