generic_connection_pool 0.1.0

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Kame Chen
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,47 @@
+= generic_connection_pool
+
+== DESCRIPTION
+Always network clients require a connection pool, like database connection, cache connection and others.
+Generic connection pool can be used with anything. It is inspired from ActiveRecord ConnectionPool.
+Sharing a limited number of network connections among many threads.
+Connections are created delayed.
+
+== USEAGE
+
+Connections can be obtained and used from a connection pool in several
+ways:
+
+1. Use connection_pool.connection to obtain a connection instance.
+ and when you're done with the connection(s) and wish it to be returned
+ to the pool, you can call connection_pool.release_connection to release
+ connection back to the connection pool.
+2. Manually check out a connection from the pool with connection_pool.checkout.
+ You are responsible for returning this connection to the pool when
+ finished by calling connection_pool.checkin(connection).
+3. Use connection_pool.with_connection(&block), which obtains a connection,
+ yields it as the sole argument to the block, and returns it to the pool
+ after the block completes.
+
+ Connections in the pool may be Adapter instance that should implete methods like
+ verify!, disconnect!, active? etc.
+
+== Example
+  require 'generic_connection_pool'
+  connection_pool = ConnectionPool.new(:size => 5, :timeout => 5) do
+    new_connection_adapter
+  end
+  connection_pool.connection
+  connection_pool.release_connection
+
+  connection = connection_pool.checkout
+  connection_pool.checkin(connection)
+
+  connection.with_connection{|connection| do_somting_with_connection}
+
+  Do something in the block, that always create an adapter instance or connect to a server.
+
+== INSTALL
+  gem install generic_connection_pool
+
+== AUTHOR
+  Kame Chen

data/Rakefile

@@ -0,0 +1,31 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'spec'
+require 'spec/rake/spectask'
+
+desc 'Default: run test.'
+task :default => :spec
+
+desc 'Test the ao_locked gem.'
+Spec::Rake::SpecTask.new(:spec) do |t|
+	t.spec_files = FileList['spec/**/*_spec.rb']
+	t.spec_opts = ['-c','-f','nested']
+end
+
+desc 'Generate documentation for the ao_locked gem.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ConnectionPool'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = eval(File.read(File.expand_path("../generic_connection_pool.gemspec", __FILE__)))
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = false
+  pkg.need_tar = false
+end

data/lib/connection_pool.rb

@@ -0,0 +1,247 @@
+require 'rubygems'
+require 'active_support/core_ext/module/synchronization'
+require 'monitor'
+require 'set'
+require 'timeout'
+# Generic connection pool class inspired from ActiveRecord ConnectionPool.
+# Sharing a limited number of network connections among many threads.
+# Connections are created delayed.
+#
+# == Introduction
+#
+# A connection pool synchronizes thread access to a limited number of
+# network connections. The basic idea is that each thread checks out a
+# database connection from the pool, uses that connection, and checks the
+# connection back in. ConnectionPool is completely thread-safe, and will
+# ensure that a connection cannot be used by two threads at the same time,
+# as long as ConnectionPool's contract is correctly followed. It will also
+# handle cases in which there are more threads than connections: if all
+# connections have been checked out, and a thread tries to checkout a
+# connection anyway, then ConnectionPool will wait until some other thread
+# has checked in a connection.
+#
+# == Obtaining (checking out) a connection
+#
+# Connections can be obtained and used from a connection pool in several
+# ways:
+#
+# 1. Use connection_pool.connection to obtain a connection instance.
+#    and when you're done with the connection(s) and wish it to be returned
+#    to the pool, you can call connection_pool.release_connection to release
+#    connection back to the connection pool.
+# 2. Manually check out a connection from the pool with connection_pool.checkout.
+#    You are responsible for returning this connection to the pool when
+#    finished by calling connection_pool.checkin(connection).
+# 3. Use connection_pool.with_connection(&block), which obtains a connection,
+#    yields it as the sole argument to the block, and returns it to the pool
+#    after the block completes.
+#
+#    Connections in the pool may be Adapter instance that should implete methods like
+#    verify!, disconnect!, active? etc.
+#
+# == Example
+#
+#   connection_pool = ConnectionPool.new(:size => 5, :timeout => 5) do
+#     new_connection_adapter
+#   end
+#   connection_pool.connection
+#   connection_pool.release_connection
+#
+#   connection = connection_pool.checkout
+#   connection_pool.checkin(connection)
+#
+#   connection.with_connection{|connection| do_somting_with_connection}
+#
+#
+#   Do something in the block, that always create an adapter instance or connect to a server.
+#
+class ConnectionPool
+  VERSION = '0.1.0'
+
+  class ConnectionTimeoutError < ::Timeout::Error
+  end
+
+  attr_reader :options
+
+  DEFAULT_OPTIONS = { :size => 5, :timeout => 5 }
+
+
+
+  # Creates a new ConnectionPool object. +spec+ is a ConnectionSpecification
+  # object which describes database connection information (e.g. adapter,
+  # host name, username, password, etc), as well as the maximum size for
+  # this ConnectionPool.
+  #
+  # The default ConnectionPool maximum size is 5.
+  def initialize(options = {}, &block)
+    @options = DEFAULT_OPTIONS.merge(options)
+
+    raise ArgumentError, "Connection pool requires a block that create a new connection!" unless block
+
+    @connection_block = block
+
+    # The cache of reserved connections mapped to threads
+    @reserved_connections = {}
+
+    # The mutex used to synchronize pool access
+    @connection_mutex = Monitor.new
+    @queue = @connection_mutex.new_cond
+
+    # default 5 second timeout
+    @timeout = @options[:timeout]
+
+    # default max pool size to 5
+    @size = @options[:size]
+
+    @connections = []
+    @checked_out = []
+  end
+
+  # Retrieve the connection associated with the current thread, or call
+  # #checkout to obtain one if necessary.
+  #
+  # #connection can be called any number of times; the connection is
+  # held in a hash keyed by the thread id.
+  def connection
+    @reserved_connections[current_connection_id] ||= checkout
+  end
+
+  # Signal that the thread is finished with the current connection.
+  # #release_connection releases the connection-thread association
+  # and returns the connection to the pool.
+  def release_connection
+    conn = @reserved_connections.delete(current_connection_id)
+    checkin conn if conn
+  end
+
+  # If a connection already exists yield it to the block.  If no connection
+  # exists checkout a connection, yield it to the block, and checkin the
+  # connection when finished.
+  def with_connection
+    fresh_connection = true unless connection_cached?
+    yield connection
+  ensure
+    release_connection if fresh_connection
+  end
+
+  # Returns true if a connection has already been opened.
+  def connected?
+    !@connections.empty?
+  end
+
+  # Disconnects all connections in the pool, and clears the pool.
+  def disconnect!
+    @reserved_connections.each do |name,conn|
+      checkin conn
+    end
+    @reserved_connections = {}
+    @connections.each do |conn|
+      conn.disconnect!
+    end
+    @connections = []
+  end
+
+  # Verify active connections and remove and disconnect connections
+  # associated with stale threads.
+  def verify_active_connections! #:nodoc:
+    clear_stale_cached_connections!
+    @connections.each do |connection|
+      connection.verify!
+    end
+  end
+
+  # Return any checked-out connections back to the pool by threads that
+  # are no longer alive.
+  def clear_stale_cached_connections!
+    keys = @reserved_connections.keys - Thread.list.find_all { |t|
+      t.alive?
+    }.map { |thread| thread.object_id }
+    keys.each do |key|
+      checkin @reserved_connections[key]
+      @reserved_connections.delete(key)
+    end
+  end
+
+  # Check-out a database connection from the pool, indicating that you want
+  # to use it. You should call #checkin when you no longer need this.
+  #
+  # This is done by either returning an existing connection, or by creating
+  # a new connection. If the maximum number of connections for this pool has
+  # already been reached, but the pool is empty (i.e. they're all being used),
+  # then this method will wait until a thread has checked in a connection.
+  # The wait time is bounded however: if no connection can be checked out
+  # within the timeout specified for this pool, then a ConnectionTimeoutError
+  # exception will be raised.
+  #
+  # Returns: connection instance return by the connection_block
+  #
+  def checkout
+    # Checkout an available connection
+    @connection_mutex.synchronize do
+      loop do
+        conn = if @checked_out.size < @connections.size
+                 checkout_existing_connection
+               elsif @connections.size < @size
+                 checkout_new_connection
+               end
+        return conn if conn
+        # No connections available; wait for one
+        if @queue.wait(@timeout)
+          next
+        else
+          # try looting dead threads
+          clear_stale_cached_connections!
+          if @size == @checked_out.size
+            raise ConnectionTimeoutError, "Could not obtain a connection within #{@timeout} seconds. The max pool size is currently #{@size}; consider increasing it."
+          end
+        end
+      end
+    end
+  end
+
+  # Check-in a connection back into the pool, indicating that you
+  # no longer need this connection.
+  #
+  # +conn+: which was obtained by earlier by calling +checkout+ on this pool.
+  def checkin(conn)
+    @connection_mutex.synchronize do
+      @checked_out.delete conn
+      @queue.signal
+    end
+  end
+
+  # whether connection cached in the current thread
+  def connection_cached?
+    !!@reserved_connections[current_connection_id]
+  end
+
+  synchronize :verify_active_connections!, :connected?, :disconnect!, :with => :@connection_mutex
+
+  private
+  def new_connection
+    @connection_block.call
+  end
+
+  def current_connection_id #:nodoc:
+    Thread.current.object_id
+  end
+
+  def checkout_new_connection
+    c = new_connection
+    @connections << c
+    checkout_and_verify(c)
+  end
+
+  def checkout_existing_connection
+    c = (@connections - @checked_out).first
+    checkout_and_verify(c)
+  end
+
+  def checkout_and_verify(c)
+    # connection must have verify! method that verify the connection active;
+    # it should auto retry to reconnect if not active.
+    c.verify!
+    @checked_out << c
+    c
+  end
+end

data/lib/generic_connection_pool.rb

@@ -0,0 +1 @@
+require File.expand_path('../connection_pool', __FILE__)

data/spec/connection_pool_spec.rb

@@ -0,0 +1,98 @@
+require File.expand_path("../", __FILE__) + '/spec_helper'
+
+def mock_connection_adapter
+  mock_connection_adapter = mock("connection_adapter")
+  mock_connection_adapter.stub!(:verify!)
+  mock_connection_adapter.stub!(:active?)
+  mock_connection_adapter.stub!(:disconnect!)
+  mock_connection_adapter
+end
+
+describe ConnectionPool do
+  describe "initialize ConnectionPool" do
+    it "raise ArgumentError if block not given" do
+      lambda{ConnectionPool.new}.should raise_error(ArgumentError)
+    end
+    it "connection pool size default 5, and can customize" do
+      ConnectionPool.new{}.options[:size].should == 5
+      ConnectionPool.new(:size => 10){}.options[:size].should == 10
+    end
+    it "connection timeout default 5, and can customize" do
+      ConnectionPool.new{}.options[:timeout].should == 5
+      ConnectionPool.new(:timeout => 10){}.options[:timeout].should == 10
+    end
+  end
+
+  describe "#connection" do
+    before do
+      @connection_pool = ConnectionPool.new{mock_connection_adapter}
+    end
+    it "should return a connection from connection pool" do
+      @connection_pool.connection.should_not be_nil
+    end
+    it "should cache the connection when call the #connection method and repeat call multi times should return the same connection if in the same thread" do
+      @connection_pool.connection.should == @connection_pool.connection
+      @connection_pool.should be_connection_cached
+    end
+    it "in different threads should return different connection when call #connection method" do
+      main_thread_connection = @connection_pool.connection
+      Thread.new{@connection_pool.connection.should_not == main_thread_connection}
+    end
+  end
+
+  describe "#release_connection" do
+    before do
+      @connection_pool = ConnectionPool.new{mock_connection_adapter}
+    end
+    it "should delete the cached connection" do
+      @connection_pool.connection
+      @connection_pool.release_connection
+      @connection_pool.should_not be_connection_cached
+    end
+    it "should check in the connection back to the connection pool" do
+      @connection_pool.connection
+      @connection_pool.release_connection
+      @connection_pool.instance_variable_get("@checked_out").should be_empty
+    end
+  end
+
+  describe "#checkout " do
+    before do
+      @connection_pool = ConnectionPool.new{mock_connection_adapter}
+      @exist_connections = []
+      5.times do
+        Thread.new{con = @connection_pool.checkout; @exist_connections << con}
+      end
+      @exist_connections.each{|con|@connection_pool.checkin(con)}
+    end
+    it "should checkout the exist connection if connections not empty" do
+      con = @connection_pool.checkout
+      @exist_connections.should include(con)
+    end
+    it "should raise error if can not obtain a connection for timeout" do
+      threads = []
+      5.times do
+        threads << Thread.new{@connection_pool.checkout; sleep(5)}
+      end
+      lambda{@connection_pool.checkout}.should raise_error(ConnectionPool::ConnectionTimeoutError)
+      threads.each(&:join)
+    end
+  end
+
+  describe "#with_connection" do
+    before do
+      @connection_pool = ConnectionPool.new{mock_connection_adapter}
+    end
+    it "should check in the connection back to the pool if it is a fresh connection" do
+      @connection_pool.with_connection{|connection|}
+      @connection_pool.should_not be_connection_cached
+      @connection_pool.instance_variable_get("@checked_out").should be_empty
+    end
+    it "should not check in the connection back to the pool if it is a cached connection" do
+      @connection_pool.connection
+      @connection_pool.with_connection{|connection|}
+      @connection_pool.should be_connection_cached
+      @connection_pool.instance_variable_get("@checked_out").should_not be_empty
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+$:.unshift(File.expand_path('../../lib',  __FILE__))
+require 'connection_pool'

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification 
+name: generic_connection_pool
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- kame
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-12-28 00:00:00 +08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: "    Always network clients require a connection pool, like database connection, cache connection and others.\n\
+  Generic connection pool can be used with anything. It is inspired from ActiveRecord ConnectionPool.\n\
+  Sharing a limited number of network connections among many threads.\n\
+  Connections are created delayed.\n"
+email: 
+- kamechb@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/connection_pool.rb
+- lib/generic_connection_pool.rb
+- spec/connection_pool_spec.rb
+- spec/spec_helper.rb
+- Rakefile
+- README
+- Gemfile
+- LICENSE
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Always network clients require a connection pool, like database connection, cache connection and others. Generic connection pool can be used with anything. It is inspired from ActiveRecord ConnectionPool. Sharing a limited number of network connections among many threads. Connections are created delayed.
+test_files: []
+