hot_tub 0.2.6 → 0.3.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YThjNDQ4Y2Q0YTg2NGNmY2RhMTVhZjg1NzNiMmM1NjZjNmE2NDUyNw==
+  data.tar.gz: !binary |-
+    ZjAwZWMwNWJkNzE4ZDhlYTg2MzIyYjdlMGM1YTIxY2JkZWQ1ZGY3ZA==
+SHA512:
+  metadata.gz: !binary |-
+    YjIyMTkxZDZkNDc2Nzc2OGVlMGI5YTgzODAxZWYwZGIzOWIxNzRkOGQ5NTM4
+    ODQ2ZTBkMThmZmU4YjIxNTg3YWM1OGNlZWRmYTExOTFlY2JkOTYyMzM0MThm
+    M2U4ODI2MmE0NWI3ZmFiZmEwMzU0ZTdlZTY2NjIyMTMyMDdjMzM=
+  data.tar.gz: !binary |-
+    M2QyMzI2OWY0MDBlZWYzYWYwYmVmNmIzMGMyZWVhOWZmYzk4NDEyNGYzYWIz
+    OWZkNmQwMDFmOTFhOTEzNDgwYTVmYzBlMTFjNjk0MTg4YzVmNzk2NjlkY2E3
+    YmNiOTUyYWE2OTNhYzFiY2EwYTc4MzhlZDg2OGYwMWU5NGE2Y2M=

data/.travis.yml

@@ -1,13 +1,13 @@
 language: ruby
 rvm:
+  - 2.1.1
+  - 2.1.0
   - 2.0.0
   - 1.9.3
-  - 1.9.2
-  - jruby-19mode
-  - rbx-19mode
+  - rbx-2
+  - rbx
   - ruby-head
   - jruby-head
 matrix:
   allow_failures:
-    - rvm: jruby-head
-    - rvm: ruby-head
+    - rvm: rbx

data/Gemfile

@@ -3,13 +3,9 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in http_hot_tub.gemspec
 gemspec
 gem 'rake'
-
 group :development do
   platform :ruby do
   	gem 'coveralls', :require => false
-    gem 'eventmachine'
-    gem 'em-http-request', '~> 1.0', :require => 'em-http'
-    gem 'em-synchrony', '~> 1.0', :require => ['em-synchrony', 'em-synchrony/em-http']
   end
   platform :jruby do
     gem 'jruby-openssl'

data/HISTORY.md

@@ -1,9 +1,17 @@
 HotTub Changelog
 =====================
 
-HEAD
+Head
 =======
 
-- Rename unsafe methods with leading "_"
-- Add register to pool to track all connections
-- EM.add_shutdown_hook for EM connections
+- Nothing yet
+
+0.3.0
+=======
+
+- Drop EM support, will move to separate gem
+- Simplify API with HotTub.new
+- Use ThreadSafe::Cache for sessions
+- Better documentation and lots of clean up
+- HotTub::Reaper for reaping in separate thread
+- HotTub::Pool now raises HotTub::Pool::Timeout instead of HotTub::BlockingTimeout

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2013 Joshua T. Mckinney
+Copyright (c) 2010-2014 Joshua T. Mckinney
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,25 +1,23 @@
 # HotTub [![Build Status](https://travis-ci.org/JoshMcKin/hot_tub.png?branch=master)](https://travis-ci.org/JoshMcKin/hot_tub) [![Coverage Status](https://coveralls.io/repos/JoshMcKin/hot_tub/badge.png?branch=master)](https://coveralls.io/r/JoshMcKin/hot_tub)
 
-A simple thread-safe connection pool and sessions gem. Out-of-the-box support for [Excon](https://github.com/geemus/excon) and
-[EM-Http-Requests](https://github.com/igrigorik/em-http-request) via [EM-Synchrony](https://github.com/igrigorik/em-synchrony). 
+A dynamic thread-safe pooling gem, when you need more than a standard static pool.
 
 ## Features
 
 ### HotTub::Pool
-* Thread safe / Fiber safe (with EM::HttpRequest + EM::Synchrony)
-* Lazy clients/connections (created only when necessary)
-* Can be used with any client library
-* Support for cleaning dirty resources
-* Set to expand pool under load that is eventually reaped back down to set size (never_block), can be disabled
-* Attempts to close clients/connections on shutdown
-
-### HotTub::Session
-* Thread safe / Fiber safe (with EM::HttpRequest + EM::Synchrony)
-* The same api as HotTub::Pool
-* Can be used with HotTub::Pool or any client library 
-* Attempts to close clients/connections on shutdown
-
-## Requirements
+A thread safe, lazy pool.
+
+* Thread safe
+* Lazy, pool starts off at 0 and grows as necessary.
+* Non-Blocking, can be configured to always return a client if your pool runs out under load. Overflow clients are returned to the pool for reuse. Once load dies, the pool is reaped down to size.
+* Can be used with any client library instance.
+* Support for cleaning dirty resources, no one likes a dirty `HotTub`
+* Support for closing resources on shutdown
+
+### HotTub::Sessions
+A [ThreadSafe::Cache](https://github.com/headius/thread_safe) where URLs are mapped to a pool or client instance.
+
+### Requirements
 HotTub is tested on MRI, JRUBY and Rubinius
 * Ruby >= 1.9
 
@@ -39,85 +37,111 @@ Run bundle:
     
     bundle install
 
-Configure Logger by creating a hot_tub.rb initializer and adding the following:
+Configure Logger by creating `config\initializers\hot_tub.rb` and adding the following:
     
     HotTub.logger = Rails.logger
 
 # Usage 
 
-## HotTub::Pool
+## HotTub
+For convenience you can initialize a new HotTub::Pool by calling HotTub.new or HotTub::Pool.new directly.
+Returns an instance of HotTub::Pool.
+
+### Redis
+    # We don't want too many connections so we set our :max_size. Under load our pool
+    # can grow to 30 connections. Once load dies down our pool can be reaped back down to 5
+    pool = HotTub::Pool.new(:size => 5, :max_size => 30, :reap_timeout => 60) { Redis.new }
+    pool.set('hot', 'stuff')
+    pool.get('hot')
+    # => 'stuff'
+
+### Net::HTTP
+
+    require 'hot_tub'
+    require 'net/http'
+
+    pool = HotTub.new(:size => 10) { 
+      uri = URI.parse("http://somewebservice.com")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = false
+      http.start
+      http
+      }
+    pool.run {|clnt| puts clnt.head('/').code }
+
+### HotTub Options    
+**size**: Default is 5. An integer that sets the size of the pool. Could be describe as minimum size the pool should grow to.
+
+**max_size**: Default is 0. An integer that represents the maximum number of connections allowed when :non_blocking is true. If set to 0, which is the default, there is no limit; connections will continue to open until load subsides long enough for reaping to occur.
+
+**wait_timeout**: Default is 10 seconds. An integer that represents the timeout when waiting for a client from the pool in seconds. After said time a HotTub::Pool::Timeout exception will be thrown
+
+**reap_timeout**: Default is 600 seconds. An integer that represents the timeout for reaping the pool in seconds.
+
+**close_out**: Default is false. A boolean value that if true force close_client to be called on checkout clients when #drain! is called
+
+**close**: Default is nil. Can be a symbol representing an method to call on a client to close the client or a lambda that accepts the client as a parameter that will close a client. The close option is performed on clients on reaping and shutdown after the client has been removed from the pool.  When nil, as is the default, no action is performed.
+
+**clean**: Default is nil. Can be a symbol representing an method to call on a client to clean the client or a lambda that accepts the client as a parameter that will clean a client. When nil, as is the default, no action is performed.
+
+**reap**: Default is nil. Can be a symbol representing an method to call on a client that returns a boolean marking a client for reaping, or a lambda that accepts the client as a parameter that returns a boolean  marking a client for reaping. When nil, as is the default, no action is performed.
+
+**no_reaper**: Default is nil. A boolean like value that if true prevents the reaper from initializing
+
+**sessions**: Default is false. Returns an instance of `HotTub::Sessions.new` that wraps clients in `HotTub::Pool.new`
+
+### With sessions
+Available via `HotTub.new(:sessions => true)` or `HotTub::Sessions.new`
 
-### EM-Http-Request
     require 'hot_tub'
-    require 'em-synchrony'
-    require 'em-synchrony/em-http'
-    EM.synchrony do {
-      pool = HotTub::Pool.new(:size => 12) { EM::HttpRequest.new("http://somewebservice.com") }
-      # Make sure we set :keepalive as true
-      pool.run { |clnt| clnt.aget(:query => results, :keepalive => true) }
-      EM.stop
+    require 'net/http'
+
+    # We must pass any pool options in our options hash, and our client block 
+    # must accept the a single argument which is normally the url
+
+    hot_tub = HotTub.new(:size => 12, :sessions => true) { |url| 
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = false
+      http.start
+      http 
     }
+    hot_tub.run("http://somewebservice.com") do |clnt|    
+      puts clnt.head('/').code
+    end
+    hot_tub.run("https://someotherwebservice.com") do |clnt|    
+      puts clnt.head('/').code
+    end
 
 ### Other
-You can use any library you want with HotTub::Pool. Close and clean can be defined at initialization 
-with lambdas, if they are not defined they are ignored.
+You can use any library you want with `HotTub::Pool`.
 
     url = "http://test12345.com"
-    pool = HotTub::Pool.new({:size => 10, :close => lambda {|clnt| clnt.close}}) { MyHttpLib.new }
-    pool.run { |clnt| clnt.get(url,query).body }
- 
-## HotTub::Session
-HotTub::Sessions are a synchronized hash of clients/pools and are implemented similar HotTub::Pool. 
-For example, Excon is thread safe but you set a single url at the client level so sessions 
-are handy if you need to access multiple urls but would prefer a single object.
+    hot_tub = HotTub.new({:size => 10, :close => lambda {|clnt| clnt.close}, :clean => :clean, :reap => :reap?}) { MyHttpLib.new }
+    hot_tub.run { |clnt| clnt.get(url,query).body }
+
+## Sessions only
+Returns a `HotTub::Sessions` instance. 
+
+[Excon](https://github.com/geemus/excon) is thread safe but you set a single url at the client level so sessions 
+are handy if you need to access multiple URLs from a single instances
     
     require 'hot_tub'
     require 'excon'
     # Our client block must accept the url argument
-    sessions = HotTub::Session.new {|url| Excon.new(url) }
+    sessions = HotTub::Sessions.new {|url| Excon.new(url) }
 
     sessions.run("http://somewebservice.com") do |clnt|    
       puts clnt.get(:query => {:some => 'stuff'}).response_header.status
     end
+
     sessions.run("https://someotherwebservice.com") do |clnt|    
       puts clnt.get(:query => {:other => 'stuff'}).response_header.status
     end
-    sessions.run("https://127.0.0.1:5252") do |clnt|    
-      puts clnt.get.response_header.status
-    end
-
-### HotTub::Session with HotTub::Pool
-Suppose you have a client that lacks pooling and session features you can use HotTub::Pool with HotTub::Sessions to get what you need.
-    
-    require 'hot_tub'
-    require "em-synchrony"
-    require "em-synchrony/em-http"
-
-    # We must tell HotTub::Session to use HotTub::Pool, pass any pool options in our 
-    # options has, and our client block must accept the url argument
-    EM.synchrony do {
-      sessions = HotTub::Session.new(:with_pool => true, :size => 12) {|url| EM::HttpRequest.new(url, :inactivity_timeout => 0) }
-
-      sessions.run("http://somewebservice.com") do |clnt|    
-        puts clnt.get(:query => results, :keepalive => true).response_header.status
-      end
-      sessions.run("https://someotherwebservice.com") do |clnt|    
-        puts clnt.get(:query => results, :keepalive => true).response_header.status
-      end
-      EM.stop
-    }
-
-## Related
-
-* [EM-Http-Request](https://github.com/igrigorik/em-http-request)
-* [EM-Synchrony](https://github.com/igrigorik/em-synchrony)
-* [Excon](https://github.com/geemus/excon) Thread safe with its own built in pool.
-* [HTTPClient](https://github.com/nahi/httpclient) A thread safe http client that supports pools and sessions all by itself.
 
-## Other Pooling Gem
+## Dependencies
 
-* [ConnectionPool](https://github.com/mperham/connection_pool)
-* [EM-Synchrony](https://github.com/igrigorik/em-synchrony) has a pool feature
+* [ThreadSafe](https://github.com/headius/thread_safe)
 
 ## Contributing to HotTub
  

data/hot_tub.gemspec

@@ -9,10 +9,12 @@ Gem::Specification.new do |s|
   s.email       = ["joshmckin@gmail.com"]
   s.homepage    = "https://github.com/JoshMcKin/hot_tub"
   s.license     = "MIT"
-  s.summary     = %q{A simple thread-safe http connection pooling gem.}
-  s.description = %q{A simple thread-safe http connection pooling gem. Out-of-the-box support for Excon and EM-Http-Request}
+  s.summary     = %q{A dynamic thread-safe pooling gem.}
+  s.description = %q{A dynamic thread-safe pooling gem, when you need more than a standard static pool.}
 
   s.rubyforge_project = "hot_tub"
+
+  s.add_runtime_dependency "thread_safe"
   
   s.add_development_dependency "rspec"
   s.add_development_dependency "sinatra"

data/lib/hot_tub.rb

@@ -1,9 +1,11 @@
 require 'thread'
+require 'thread_safe'
 require 'logger'
 require "hot_tub/version"
 require "hot_tub/known_clients"
+require "hot_tub/reaper"
 require "hot_tub/pool"
-require "hot_tub/session"
+require "hot_tub/sessions"
 
 module HotTub
   @@logger = Logger.new(STDOUT)
@@ -15,14 +17,6 @@ module HotTub
     @@logger = logger
   end
 
-  def self.em?
-    (defined?(EM))
-  end
-
-  def self.em_synchrony?
-    (defined?(EM::Synchrony))
-  end
-
   def self.jruby?
     (defined?(JRUBY_VERSION))
   end
@@ -31,11 +25,12 @@ module HotTub
     defined?(RUBY_ENGINE) and RUBY_ENGINE == 'rbx'
   end
 
-  def self.hot_at_exit with_em=false, &blk
-    if with_em
-      EM.add_shutdown_hook &blk
+  def self.new(opts={},&client_block)
+    if opts[:sessions] == true
+      opts[:with_pool] = true
+      Sessions.new(opts,&client_block)
     else
-      at_exit &blk
+      Pool.new(opts,&client_block)
     end
   end
 end

data/lib/hot_tub/known_clients.rb

@@ -4,44 +4,62 @@ module HotTub
       "Excon::Connection" => {
         :close => lambda { |clnt| clnt.reset }
       },
-      'EventMachine::HttpConnection' => {
+      "Net::HTTP" => {
         :close => lambda { |clnt|
-          if clnt.conn
-            clnt.conn.close_connection
-            clnt.instance_variable_set(:@deferred, true)
+          begin
+            clnt.finish
+          rescue IOError
+            nil
           end
-        },
-        :clean => lambda { |clnt|
-          if clnt.conn && clnt.conn.error?
-            HotTub.logger.info "Sanitizing connection : #{EventMachine::report_connection_error_status(clnt.conn.instance_variable_get(:@signature))}"
-            clnt.conn.close_connection
-            clnt.instance_variable_set(:@deferred, true)
-          end
-          clnt
         }
       }
     }
-    attr_accessor :options
     # Attempts to clean the provided client, checking the options first for a clean block
     # then checking the known clients
     def clean_client(clnt)
-      return @options[:clean].call(clnt) if @options && @options[:clean] && @options[:clean].is_a?(Proc)
-      if settings = KNOWN_CLIENTS[clnt.class.name]
-        settings[:clean].call(clnt) if settings[:clean].is_a?(Proc)
+      begin
+        action = (@clean_client || known_client_action(clnt,:clean))
+        preform_client_action(clnt,action) if action
+      rescue => e
+        HotTub.logger.error "There was an error cleaning one of your #{self.class.name} clients: #{e}"
       end
     end
 
     # Attempts to close the provided client, checking the options first for a close block
     # then checking the known clients
     def close_client(clnt)
-      return @options[:close].call(clnt) if @options && @options[:close] && @options[:close].is_a?(Proc)
-      if settings = KNOWN_CLIENTS[clnt.class.name]
-        begin
-          settings[:close].call(clnt) if settings[:close].is_a?(Proc)
-        rescue => e
-          HotTub.logger.error "There was an error close one of your #{self.class.name} connections: #{e}"
-        end
+      begin
+        action = (@close_client || known_client_action(clnt,:close))
+        preform_client_action(clnt,action) if action
+      rescue => e
+        HotTub.logger.error "There was an error closing one of your #{self.class.name} clients: #{e}"
+      end
+    end
+
+    # Attempts to determine if a client should be reaped, block should return a boolean
+    def reap_client?(clnt)
+      begin
+        action = (@reap_client || known_client_action(clnt,:reap))
+        return preform_client_action(clnt,action) if action
+      rescue => e
+        HotTub.logger.error "There was an error reaping one of your #{self.class.name} clients: #{e}"
+      end
+      return false
+    end
+
+    private
+
+    def known_client_action(clnt,key)
+      (KNOWN_CLIENTS[clnt.class.name] && KNOWN_CLIENTS[clnt.class.name][key])
+    end
+
+    def preform_client_action(clnt,action)
+      if action.is_a?(Proc)
+        return action.call(clnt)
+      elsif action.is_a?(Symbol)
+        return clnt.send(action)
       end
+      false
     end
   end
 end

data/lib/hot_tub/pool.rb

@@ -1,52 +1,117 @@
 module HotTub
   class Pool
     include HotTub::KnownClients
-    attr_reader :current_size, :fetching_client, :last_activity
+    include HotTub::Reaper::Mixin
+    attr_reader :current_size, :last_activity
 
     # Thread-safe lazy connection pool
     #
-    # == Example EM-Http-Request
-    #     pool = HotTub::Pool.new { EM::HttpRequest.new("http://somewebservice.com") }
-    #     pool.run {|clnt| clnt.get(:keepalive => true).body }
+    # == Example Net::HTTP
+    #     pool = HotTub::Pool.new(:size => 10) {
+    #       uri = URI.parse("http://somewebservice.com")
+    #       http = Net::HTTP.new(uri.host, uri.port)
+    #       http.use_ssl = false
+    #       http.start
+    #       http
+    #     }
+    #     pool.run {|clnt| puts clnt.head('/').code }
+    #
+    # == Example Redis
+    #     # We don't want too many connections so we set our :max_size Under load our pool
+    #     # can grow to 30 connections. Once load dies down our pool can be reaped back down to 5
+    #     pool = HotTub::Pool.new(:size => 5, :max_size => 30, :reap_timeout => 60) { Redis.new }
+    #     pool.set('hot', 'stuff')
+    #     pool.get('hot')
+    #     # => 'stuff'
     #
     # HotTub::Pool defaults never_block to true, which means if we run out of
-    # connections simply create a new client to continue operations.
-    # The pool will grow and extra connections will be resued until activity dies down.
+    # clients simply create a new client to continue operations.
+    # The pool will grow and extra clients will be reused until activity dies down.
     # If you would like to block and possibly throw an exception rather than temporarily
-    # grow the set :size, set :never_block to false; blocking_timeout defaults to 10 seconds.
+    # grow the set :size, set :never_block to false; wait_timeout defaults to 10 seconds.
     #
-    # == Example without #never_block (will BlockingTimeout exception)
-    #     pool = HotTub::Pool.new(:size => 1, :never_block => false, :blocking_timeout => 0.5) { EM::HttpRequest.new("http://somewebservice.com") }
+    # == Example with set pool size (will throw HotTub::Pool::Timeout exception)
+    #     pool = HotTub::Pool.new(:size => 1, :max_size => 1, :wait_timeout => 0.5) {
+    #       uri = URI.parse("http://someslowwebservice.com")
+    #       http = Net::HTTP.new(uri.host, uri.port)
+    #       http.use_ssl = false
+    #       http.start
+    #       http
+    #     }
+    #     pool.run { |clnt| puts clnt.head('/').code }
     #
     #     begin
-    #       pool.run {|clnt| clnt.get(:keepalive => true).body }
-    #     rescue HotTub::BlockingTimeout => e
-    #       puts "Our pool ran out: {e}"
+    #       pool.run { |clnt| puts clnt.head('/').code }
+    #     rescue HotTub::Pool::Timeout => e
+    #       puts "Waited too long for a client: {e}"
     #     end
     #
-    def initialize(options={},&client_block)
+    #
+    # === OPTIONS
+    #
+    # [:size]
+    #   Default is 5. An integer that sets the size of the pool. Could be describe as minimum size the pool should
+    #   grow to.
+    # [:max_size]
+    #   Default is 0. An integer that represents the maximum number of connections allowed when :non_blocking is true.
+    #   If set to 0, which is the default, there is no limit; connections will continue to open until load subsides
+    #   long enough for reaping to occur.
+    # [:wait_timeout]
+    #   Default is 10 seconds. An integer that represents the timeout when waiting for a client from the pool
+    #   in seconds. After said time a HotTub::Pool::Timeout exception will be thrown
+    # [:reap_timeout]
+    #   Default is 600 seconds. An integer that represents the timeout for reaping the pool in seconds.
+    # [:close_out]
+    #   Default is nil. A boolean like value that if it can be interpreted as true force close_client to be called
+    #   on checkout clients when #drain! is called
+    # [:close]
+    #   Default is nil. Can be a symbol representing an method to call on a client to close the client or a lambda
+    #   that accepts the client as a parameter that will close a client. The close option is performed on clients
+    #   on reaping and shutdown after the client has been removed from the pool.  When nil, as is the default, no
+    #   action is performed.
+    # [:clean]
+    #   Default is nil. Can be a symbol representing an method to call on a client to clean the client or a lambda
+    #   that accepts the client as a parameter that will clean a client. When nil, as is the default, no action is
+    #   performed.
+    # [:reap]
+    #   Default is nil. Can be a symbol representing an method to call on a client that returns a boolean marking
+    #   a client for reaping, or a lambda that accepts the client as a parameter that returns a boolean boolean
+    #   marking a  client for reaping. When nil, as is the default, no action is performed.
+    # [:no_reaper]
+    #   Default is nil. A boolean like value that if true prevents the reaper from initializing
+    #
+    def initialize(opts={},&new_client)
       raise ArgumentError, 'a block that initializes a new client is required' unless block_given?
-      @client_block = client_block
-      @options = {
-        :size => 5,
-        :never_block => true,     # Return new client if we run out
-        :blocking_timeout => 10,  # in seconds
-        :close => nil,            # => lambda {|clnt| clnt.close}
-        :clean => nil             # => lambda {|clnt| clnt.clean}
-      }.merge(options)
-      @pool             = []    # stores available connection
-      @register         = []    # stores all connections at all times
-      @current_size     = 0
-      @pool_mutex       = (em_client? ? EM::Synchrony::Thread::Mutex.new : Mutex.new)
-      @last_activity    = Time.now
-      @fetching_client  = false
-      HotTub.hot_at_exit( em_client? ) {close_all}
+
+      @size             = (opts[:size] || 5)                # in seconds
+      @wait_timeout     = (opts[:wait_timeout] || 10)   # in seconds
+      @reap_timeout     = (opts[:reap_timeout] || 600)      # the interval to reap connections in seconds
+      @close_out        = opts[:close_out]                  # if true on drain! call close_client block on checked out clients
+      @max_size         = (opts[:max_size] || 0)            # maximum size of pool when non-blocking, 0 means no limit
+
+      @close_client     = opts[:close]                    # => lambda {|clnt| clnt.close} or :close
+      @clean_client     = opts[:clean]                    # => lambda {|clnt| clnt.clean} or :clean
+      @reap_client      = opts[:reap]                     # => lambda {|clnt| clnt.reap?} or :reap? # should return boolean
+      @new_client       = new_client
+
+      @pool             = []    # stores available clients
+      @pool.taint
+      @out              = []    # stores all checked out clients
+      @out.taint
+
+      @mutex            = Mutex.new
+      @cond             = ConditionVariable.new
+
+      @shutdown         = false                 # Kills reaper when true
+      @reaper           = Reaper.spawn(self) unless opts[:no_reaper]
+
+      at_exit {shutdown!}
     end
 
     # Hand off to client.run
     def run(&block)
-      clnt = client
       if block_given?
+        clnt = client
         return block.call(clnt) if clnt
       else
         raise ArgumentError, 'Run requires a block.'
@@ -55,117 +120,189 @@ module HotTub
       push(clnt) if clnt
     end
 
-    # Calls close on all connections and reset the pools
-    def close_all
-      @pool_mutex.synchronize do
-        while clnt = @register.pop
-          @pool.delete(clnt)
-          begin
-            close_client(clnt)
-          rescue => e
-            HotTub.logger.error "There was an error close one of your HotTub::Pool connections: #{e}"
-          end
+    # Clean all clients currently checked into the pool.
+    # Its possible clients may be returned to the pool after cleaning
+    def clean!
+      @mutex.synchronize do
+        @pool.each do |clnt|
+          clean_client(clnt)
         end
-        @current_size = 0
       end
     end
 
-    private
+    # Drain the pool of all clients currently checked into the pool.
+    # After draining, wake all sleeping threads to allow repopulating the pool
+    # or if shutdown allow threads to quickly finish their work
+    # Its possible clients may be returned to the pool after cleaning
+    def drain!
+      @mutex.synchronize do
+        while clnt = (@pool.pop || (@close_out && @out.pop))
+          close_client(clnt)
+        end
+        @cond.broadcast
+      end
+    end
+    alias :close! :drain!
+    alias :close_all! :drain!
+
+    # Kills the reaper and drains the pool.
+    def shutdown!
+      @shutdown = true
+      drain!
+    end
 
-    def em_client?
-      begin
-        (HotTub.em_synchrony? && @client_block.call.is_a?(EventMachine::HttpConnection))
-      rescue
-        false
+    # Remove and close extra clients
+    # Releases mutex each iteration because
+    # reaping is low priority action
+    def reap!
+      start = Time.now
+      loop do
+        reaped = nil
+        @mutex.synchronize do
+          reaped = @pool.shift if _reap?
+        end
+        if reaped
+          close_client(reaped)
+        else
+          break
+        end
       end
     end
 
+    def never_block?
+      (@max_size == 0)
+    end
+
+    private
+
     # Returns an instance of the client for this pool.
     def client
-      clnt = nil
-      alarm = (Time.now + @options[:blocking_timeout])
-      # block until we get an available client or raise Timeout::Error
-      while clnt.nil?
-        raise_alarm if alarm <= Time.now
-        clnt = pop
-      end
-      clean_client(clnt)
+      clnt = pop
+      clean_client(clnt) if clnt
       clnt
     end
 
+    def alarm_time
+      (Time.now + @wait_timeout)
+    end
+
+    def raise_alarm?(time)
+      (time <= Time.now)
+    end
+
     def raise_alarm
       message = "Could not fetch a free client in time. Consider increasing your pool size."
       HotTub.logger.error message
-      raise BlockingTimeout, message
+      raise Timeout, message
     end
 
     # Safely add client back to pool, only if
     # that clnt is registered
     def push(clnt)
-      @pool_mutex.synchronize do
-        if @register.include?(clnt)
-          @pool << clnt 
-        else
-          close_client(clnt)
+      if clnt
+        @mutex.synchronize do
+          @out.delete(clnt)
+          unless @shutdown
+            @pool << clnt
+            @cond.signal
+          end
         end
+        close_client(clnt) if @shutdown
       end
-      nil # make sure never return the pool
+      nil
     end
 
     # Safely pull client from pool, adding if allowed
     def pop
-      @fetching_client = true # kill reap_pool
-      @pool_mutex.synchronize do
-        _add if add?
-        clnt = @pool.pop # get warm connection
-        if (clnt.nil? && @options[:never_block])
-          _add
-          clnt = @pool.pop
+      clnt = nil
+      alarm = alarm_time
+      while clnt.nil?
+        break if @shutdown
+        raise_alarm if raise_alarm?(alarm)
+        @mutex.synchronize do
+          if (_space? || _add)
+            @out << clnt = @pool.pop
+          else
+            @cond.wait(@mutex,@wait_timeout)
+          end
         end
-        @fetching_client = false
-        clnt
       end
-    ensure
-      reap_pool if reap_pool?
+      clnt
     end
 
-    # create a new client from base client
-    def new_client
-      @client_block.call
+    ### START VOLATILE METHODS ###
+
+    # _empty? is volatile; and may cause be inaccurate
+    # if called outside @mutex.synchronize {}
+    def _empty?
+      @pool.empty?
     end
 
-    # Only want to add a client if the pool is empty in keeping with
-    # a lazy model.
-    def add?
-      (@pool.length == 0 && (@options[:size] > @current_size))
+    # _space? is volatile; and may be inaccurate
+    # if called outside @mutex.synchronize {}
+    def _space?
+      !_empty?
     end
 
-    def reap_pool?
-      (!@fetching_client && (@current_size > @options[:size]) && ((@last_activity + (600)) < Time.now))
+    # Returns the total number of clients in the pool
+    # and checked out. _total_current_size is volatile and
+    # may be inaccurate if called outside @mutex.synchronize {}
+    def _total_current_size
+      (@pool.length + @out.length)
     end
 
-    # Remove extra connections from front of pool
-    def reap_pool
-      @pool_mutex.synchronize do
-        if reap_pool? && clnt = @pool.shift
-          @register.delete(clnt)
-          @current_size -= 1
-          close_client(clnt)
-        end
-      end
+    # Return true if we have reached our limit set by the :size option
+    # _less_than_size? is volatile; and may be inaccurate
+    # if called outside @mutex.synchronize {}
+    def _less_than_size?
+      (_total_current_size < @size)
+    end
+
+    # Return true if we have reached our limit set by the :max_size option
+    # _less_than_max? is volatile; and may be inaccurate
+    # if called outside @mutex.synchronize {}
+    def _less_than_max?
+      (_total_current_size < @max_size)
+    end
+
+    # We only want to add a client if the pool is empty in keeping with
+    # a lazy model. If the pool is empty we can only add clients if
+    # never_block? is true or there is room to grow. _add? is volatile;
+    # and may be in accurate if called outside @mutex.synchronize {}
+    def _add?
+      (_empty? && (never_block? || _less_than_size?|| _less_than_max?))
     end
 
-    # _add is volatile; and may cause theading issues 
-    # if called outside @pool_mutex.synchronize {}
+    # Adds a new client to the pool if its allowed
+    # _add is volatile; and may cause threading issues
+    # if called outside @mutex.synchronize {}
     def _add
-      @last_activity = Time.now
-      @current_size += 1
-      nc = new_client
+      return false unless _add?
+      nc = @new_client.call
       HotTub.logger.info "Adding HotTub client: #{nc.class.name} to pool"
-      @register << nc
       @pool << nc
+      true
     end
-    # end volatile 
+
+    # Returns true if we have clients in the pool, the pool
+    # is not shutting down, and there is overflow or the first
+    # client in the pool is ready for reaping. _reap_pool? is
+    # volatile; and may be inaccurate if called outside
+    # @mutex.synchronize {}
+    def _reap?
+      (_space? && !@shutdown && (_overflow? || reap_client?(@pool[0])))
+    end
+
+    # Returns true if the pool is greater than the :size option and the
+    # pool has been stagnant long enough to allow for reaping (we don't
+    # want to reap under load). _overflow_expired? is volatile; and may
+    # be inaccurate if called outside @mutex.synchronize {}
+    def _overflow?
+      (@pool.length > @size)
+    end
+
+    ### END VOLATILE METHODS ###
+    Timeout = Class.new(Exception) # HotTub::Pool::Timeout
   end
-  class BlockingTimeout < StandardError;end
+
 end