connection_pool 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b24f806aed835d638868cfeee4d30cd53b32c561
-  data.tar.gz: eeb809403e4ae18c350800712b97d9b65cff0194
+  metadata.gz: d46787d5f1cdf8901aff57ded2eb518418fea245
+  data.tar.gz: 0ffd3058f4269e9155070e901dd4eb29db2e81d7
 SHA512:
-  metadata.gz: f815103822aaced056e316cf955a3d6a35fbb07b9e87d6f646e83a324e8c28aba570c55f0561ef94bcd76134670320f441c1141bcc2103f82843aa17d0ab42a2
-  data.tar.gz: d5883346fa243b8d0de199288722d4ec84092dbe4a8c984c33c4c48c3deb4f4ce0d11187be0a83941bac1231341b4a98f7f2d5968c6d4f5c159df6a15eddc365
+  metadata.gz: 9adff3406500853bcf8fcd480cce510cab1cf03b3d31cf2429648e92973b012000ba9d4a8e252efbce486f38f00b7df86527073d9d3f0212e967d8624675fe03
+  data.tar.gz: 609a9f24d0472bf9df5989e6830118873a9ae779738945e80c7b5e7010aa205b545af949fc4fa2233ccb5bb4379e9b54d2118f42c4900ac81bb262e790b53a53

data/Changes.md

@@ -1,3 +1,11 @@
+2.1.0
+------
+
+- Refactoring to better support connection pool subclasses [drbrain,
+  #55]
+- `with` should return value of the last expression [#59]
+
+
 2.0.0
 -----
 

data/README.md

@@ -68,6 +68,19 @@ end
 Once you've ported your entire system to use `with`, you can simply remove
 `Wrapper` and use the simpler and faster `ConnectionPool`.
 
+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.
+
+```ruby
+cp = ConnectionPool.new { Redis.new }
+cp.shutdown { |conn| conn.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.
+
 
 Notes
 -----

data/lib/connection_pool.rb

@@ -66,7 +66,7 @@ class ConnectionPool
 
     if stack.empty?
       timeout = options[:timeout] || @timeout
-      conn = @available.pop(timeout)
+      conn = @available.pop(timeout: timeout)
     else
       conn = stack.last
     end

data/lib/connection_pool/timed_stack.rb

@@ -1,10 +1,37 @@
 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
+# number.
+
+# Examples:
+#
+#    ts = TimedStack.new(1) { MyConnection.new }
+#
+#    # fetch a connection
+#    conn = ts.pop
+#
+#    # return a connection
+#    ts.push conn
+#
+#    conn = ts.pop
+#    ts.pop timeout: 5
+#    #=> raises Timeout::Error after 5 seconds
+
 class ConnectionPool::TimedStack
 
+  ##
+  # Creates a new pool with +size+ connections that are created from the given
+  # +block+.
+
   def initialize(size = 0, &block)
     @create_block = block
     @created = 0
@@ -15,12 +42,16 @@ class ConnectionPool::TimedStack
     @shutdown_block = nil
   end
 
-  def push(obj)
+  ##
+  # 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
         @shutdown_block.call(obj)
       else
-        @que.push obj
+        store_connection obj, options
       end
 
       @resource.broadcast
@@ -28,16 +59,28 @@ class ConnectionPool::TimedStack
   end
   alias_method :<<, :push
 
-  def pop(timeout=0.5)
+  ##
+  # 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+ 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.
+
+  def pop(timeout = 0.5, options = {})
+    options, timeout = timeout, 0.5 if Hash === timeout
+    timeout = options.fetch :timeout, timeout
+
     deadline = Time.now + timeout
     @mutex.synchronize do
       loop do
         raise ConnectionPool::PoolShuttingDownError if @shutdown_block
-        return @que.pop unless @que.empty?
-        unless @created == @max
-          @created += 1
-          return @create_block.call
-        end
+        return fetch_connection(options) if connection_stored?(options)
+
+        connection = try_create(options)
+        return connection if connection
+
         to_wait = deadline - Time.now
         raise Timeout::Error, "Waited #{timeout} sec" if to_wait <= 0
         @resource.wait(@mutex, to_wait)
@@ -45,6 +88,10 @@ class ConnectionPool::TimedStack
     end
   end
 
+  ##
+  # Shuts down the TimedStack which prevents connections from being checked
+  # out.  The +block+ is called once for each connection on the stack.
+
   def shutdown(&block)
     raise ArgumentError, "shutdown must receive a block" unless block_given?
 
@@ -52,18 +99,75 @@ class ConnectionPool::TimedStack
       @shutdown_block = block
       @resource.broadcast
 
-      @que.size.times do
-        conn = @que.pop
-        block.call(conn)
-      end
+      shutdown_connections
     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
+
+  private
+
+  ##
+  # 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
+
+  ##
+  # 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
+  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)
+      @shutdown_block.call(conn)
+    end
+  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
+  end
+
+  ##
+  # This is an extension point for TimedStack and is called with a mutex.
+  #
+  # 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
+      @created += 1
+      @create_block.call
+    end
+  end
 end

data/lib/connection_pool/version.rb

@@ -1,3 +1,3 @@
 class ConnectionPool
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 end

data/test/test_connection_pool.rb

@@ -147,6 +147,11 @@ class TestConnectionPool < Minitest::Test
     assert_same conn, t2.value
   end
 
+  def test_returns_value
+    pool = ConnectionPool.new(:timeout => 0, :size => 1) { Object.new }
+    assert_equal 1, pool.with {|o| 1 }
+  end
+
   def test_checkin_never_checkout
     pool = ConnectionPool.new(:timeout => 0, :size => 1) { Object.new }
 

data/test/test_connection_pool_timed_stack.rb

@@ -44,6 +44,14 @@ class TestConnectionPoolTimedStack < Minitest::Test
   end
 
   def test_pop_empty
+    e = assert_raises Timeout::Error do
+      @stack.pop timeout: 0
+    end
+
+    assert_equal 'Waited 0 sec', e.message
+  end
+
+  def test_pop_empty_2_0_compatibility
     e = assert_raises Timeout::Error do
       @stack.pop 0
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: connection_pool
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Mike Perham
@@ -9,34 +9,34 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-14 00:00:00.000000000 Z
+date: 2014-11-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 5.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 5.0.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: Generic connection pool for Ruby
@@ -47,8 +47,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .travis.yml
+- ".gitignore"
+- ".travis.yml"
 - Changes.md
 - Gemfile
 - LICENSE
@@ -71,17 +71,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.4.1
 signing_key: 
 specification_version: 4
 summary: Generic connection pool for Ruby