hot_tub 0.4.0 → 0.5.0

data/lib/hot_tub/pool.rb

@@ -2,6 +2,8 @@ module HotTub
   class Pool
     include HotTub::KnownClients
     include HotTub::Reaper::Mixin
+
+    attr_accessor :name
     attr_reader :current_size, :last_activity
 
     # Thread-safe lazy connection pool
@@ -38,48 +40,58 @@ module HotTub
     #       http.start
     #       http
     #     }
-    #     pool.run { |clnt| puts clnt.head('/').code }
+    #     pool.run { |clnt| s clnt.head('/').code }
     #
     #     begin
-    #       pool.run { |clnt| puts clnt.head('/').code }
+    #       pool.run { |clnt| s clnt.head('/').code }
     #     rescue HotTub::Pool::Timeout => e
     #       puts "Waited too long for a client: {e}"
     #     end
     #
     #
     # === OPTIONS
+    # [:name]
+    #     A string representing the name of your pool used for logging.
     #
     # [: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]
     #   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]
+    #
+    # [: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)
+    # [:reaper]
+    #   If set to false prevents, a HotTub::Reaper from initializing and all reaping will occur when the clients
+    #   are returned to the pool, blocking the current thread.
+    #
+    # [:reap_timeout]
+    #   Default is 600 seconds. An integer that represents the timeout for reaping the pool in seconds.
+    #
+    def initialize(opts={},&client_block)
       raise ArgumentError, 'a block that initializes a new client is required' unless block_given?
-
+      @name             = (opts[:name] || self.class.name)
       @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
@@ -87,38 +99,39 @@ module HotTub
 
       @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
+      @reap_client      = opts[:reap?]                    # => lambda {|clnt| clnt.reap?} or :reap? # should return boolean
+      @client_block     = client_block
 
-      @_pool             = []    # stores available clients
+      @_pool            = []    # stores available clients
       @_pool.taint
-      @_out              = []    # stores all checked out clients
+      @_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]
+      @shutdown         = false
+      @blocking_reap    = (opts[:reaper] == false && !opts[:sessions])
+      @reaper           = Reaper.spawn(self) unless (opts[:sessions] || (opts[:reaper] == false))
+
+      @never_block      = (@max_size == 0)
 
-      at_exit {shutdown!}
+      at_exit {shutdown!} unless opts[:sessions]
     end
 
-    # Hand off to client.run
+    # Preform an operations with a client/connection.
+    # Requires a block that receives the client.
     def run
-      if block_given?
-        clnt = client
-        return yield clnt if clnt
-      else
-        raise ArgumentError, 'Run requires a block.'
-      end
+      clnt = pop
+      yield clnt
     ensure
-      push(clnt) if clnt
+      push(clnt)
     end
 
     # Clean all clients currently checked into the pool.
     # Its possible clients may be returned to the pool after cleaning
     def clean!
+      HotTub.logger.info "[HotTub] Cleaning pool #{@name}!" if HotTub.logger
       @mutex.synchronize do
         @_pool.each do |clnt|
           clean_client(clnt)
@@ -131,12 +144,15 @@ module HotTub
     # or if shutdown allow threads to quickly finish their work
     # Its possible clients may be returned to the pool after cleaning
     def drain!
+      HotTub.logger.info "[HotTub] Draining pool #{@name}!" if HotTub.logger
       @mutex.synchronize do
         begin
-          while clnt = (@_pool.pop || @_out.pop)
+          while clnt = @_pool.pop
             close_client(clnt)
           end
         ensure
+          @_out.clear
+          @_pool.clear
           @cond.broadcast
         end
       end
@@ -147,9 +163,10 @@ module HotTub
     # or if shutdown allow threads to quickly finish their work
     # Clients from the previous pool will not return to pool.
     def reset!
+      HotTub.logger.info "[HotTub] Resetting pool #{@name}!" if HotTub.logger
       @mutex.synchronize do
         begin
-          while clnt = (@_pool.pop || @_out.pop)
+          while clnt = @_pool.pop
             close_client(clnt)
           end
           if @reaper
@@ -157,6 +174,8 @@ module HotTub
             @reaper = Reaper.spawn(self)
           end
         ensure
+          @_out.clear
+          @_pool.clear
           @cond.broadcast
         end
       end
@@ -165,21 +184,36 @@ module HotTub
 
     # Kills the reaper and drains the pool.
     def shutdown!
+      HotTub.logger.info "[HotTub] Shutting down pool #{@name}!" if HotTub.logger
       @shutdown = true
-      kill_reaper if @reaper
-    ensure
-      drain!
+      @mutex.synchronize do
+        begin
+          while clnt = @_pool.pop
+            close_client(clnt)
+          end
+          kill_reaper if @reaper
+        ensure
+          @_out.clear
+          @_pool.clear
+          @cond.broadcast
+        end
+      end
+      nil
     end
 
     # Remove and close extra clients
     # Releases mutex each iteration because
     # reaping is a low priority action
     def reap!
-      loop do
-        break if @shutdown
-        reaped = nil
+      HotTub.logger.info "[HotTub] Reaping pool #{@name}!" if HotTub.log_trace?
+      reaped = nil
+      while !@shutdown
         @mutex.synchronize do
-          reaped = @_pool.shift if _reap?
+          if _reap?
+            reaped = @_pool.shift
+          else
+            reaped = nil
+          end
         end
         if reaped
           close_client(reaped)
@@ -189,32 +223,20 @@ module HotTub
       end
     end
 
-    def never_block?
-      (@max_size == 0)
-    end
-
     def current_size
       @mutex.synchronize do
         _total_current_size
       end
     end
 
-    private
-
-    # Returns an instance of the client for this pool.
-    def client
-      clnt = pop
-      clean_client(clnt) if clnt
-      clnt
+    # We must reset our @never_block cache
+    # when we set max_size after initialization
+    def max_size=max_size
+      @never_block = (max_size == 0)
+      @max_size = max_size
     end
 
-    def alarm_time
-      (Time.now + @wait_timeout)
-    end
-
-    def raise_alarm?(time)
-      (time <= Time.now)
-    end
+    private
 
     ALARM_MESSAGE = "Could not fetch a free client in time. Consider increasing your pool size."
 
@@ -225,41 +247,46 @@ module HotTub
     end
 
     # Safely add client back to pool, only if
-    # that clnt is registered
+    # that client is registered
     def push(clnt)
       if clnt
         @mutex.synchronize do
           begin
-            if @_out.delete(clnt)
-              unless @shutdown
-                @_pool << clnt
-              end
+            if !@shutdown && @_out.delete(clnt)
+              @_pool << clnt
+            else 
+              close_client(clnt)
+              HotTub.logger.info "[HotTub] An orphaned client attempted to return to #{@name}." if HotTub.log_trace?
             end
           ensure
             @cond.signal
           end
         end
-        close_client(clnt) if @shutdown
-        reap! unless @reaper
+        reap! if @blocking_reap
       end
       nil
     end
 
     # Safely pull client from pool, adding if allowed
     def pop
+      alarm = (Time.now + @wait_timeout)
       clnt = nil
-      alarm = alarm_time
-      while clnt.nil?
-        break if @shutdown
-        raise_alarm if raise_alarm?(alarm)
+      dirty = false
+      while !@shutdown
+        raise_alarm if (Time.now > alarm)
         @mutex.synchronize do
-          if clnt = (@_pool.pop || _fetch_new)
+          if clnt = @_pool.pop
+            dirty = true
+            @_out << clnt
+          elsif clnt = _fetch_new(&@client_block)
             @_out << clnt
           else
             @cond.wait(@mutex,@wait_timeout)
           end
         end
+        break if clnt
       end
+      clean_client(clnt) if dirty && clnt 
       clnt
     end
 
@@ -272,28 +299,14 @@ module HotTub
       (@_pool.length + @_out.length)
     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
-
-    # Adds a new client to the pool if its allowed
+    # Returns a new client if its allowed.
     # _add is volatile; and may cause threading issues
     # if called outside @mutex.synchronize {}
     def _fetch_new
-      return nil unless (@_pool.empty? && (never_block? || _less_than_size?|| _less_than_max?))
-      nc = @new_client.call
-      HotTub.logger.info "Adding HotTub client: #{nc.class.name} to pool" if HotTub.logger
-      nc
+      if (@never_block || (_total_current_size < @max_size))
+        HotTub.logger.info "[HotTub] Adding client: #{nc.class.name} to #{@name}." if HotTub.log_trace?
+        yield        
+      end
     end
 
     # Returns true if we have clients in the pool, the pool
@@ -302,7 +315,7 @@ module HotTub
     # volatile; and may be inaccurate if called outside
     # @mutex.synchronize {}
     def _reap?
-      ( !@_pool.empty? && !@shutdown && ((@_pool.length > @size) || reap_client?(@_pool[0])))
+      (!@shutdown && ((@_pool.length > @size) || reap_client?(@_pool[0])))
     end
 
     ### END VOLATILE METHODS ###

data/lib/hot_tub/reaper.rb

@@ -15,7 +15,7 @@ module HotTub
             break if obj.shutdown
             sleep(obj.reap_timeout || 600)
           rescue Exception => e
-            HotTub.logger.error "HotTub::Reaper for #{obj.class.name} terminated with exception: #{e.message}" if HotTub.logger
+            HotTub.logger.error "[HotTub] Reaper for #{obj.class.name} terminated with exception: #{e.message}" if HotTub.logger
             HotTub.logger.error e.backtrace.map {|line| " #{line}"} if HotTub.logger
             break
           end
@@ -28,7 +28,19 @@ module HotTub
 
     # Mixin to dry up Reaper usage
     module Mixin
-      attr_reader :reap_timeout, :reaper, :shutdown
+      attr_reader :reap_timeout, :shutdown, :reaper
+
+      # Setting reaper kills the current reaper. 
+      # If the values is truthy a new HotTub::Reaper
+      # is created.
+      def reaper=reaper
+        kill_reaper
+        if reaper 
+          @reaper = HotTub::Reaper.new(self)
+        else
+          @reaper = false
+        end
+      end
 
       def reap!
         raise NoMethodError.new('#reap! must be redefined in your class')

data/lib/hot_tub/sessions.rb

@@ -3,128 +3,161 @@ module HotTub
   class Sessions
     include HotTub::KnownClients
     include HotTub::Reaper::Mixin
+    attr_accessor :name
 
-    # HotTub::Session is a ThreadSafe::Cache where URLs are mapped HotTub::Pools.
-    #
+    # HotTub::Sessions simplifies managing multiple Pools in a single object
+    # and using a single Reaper.
     #
     # == Example:
-    # You can initialize a HotTub::Pool with each client by passing :with_pool as true and any pool options
-    #   sessions = HotTub::Sessions.new(:size => 12) {
-    #       uri = URI.parse("http://somewebservice.com")
-    #       http = Net::HTTP.new(uri.host, uri.port)
-    #       http.use_ssl = false
-    #       http.start
-    #       http
-    #     }
     #
-    #   sessions.run("http://wwww.yahoo.com") do |conn|
+    #   url  = "http://somewebservice.com"
+    #   url2 = "http://somewebservice2.com"
+    #
+    #   sessions = HotTub::Sessions
+    #   sessions.add(url,{:size => 12}) {
+    #     uri = URI.parse(url)
+    #     http = Net::HTTP.new(uri.host, uri.port)
+    #     http.use_ssl = false
+    #     http.start
+    #     http
+    #    }
+    #   sessions.add(url2,{:size => 5}) {
+    #     Excon.new(url2)
+    #    }
+    #
+    #   sessions.run(url) do |conn|
     #     p conn.head('/').code
     #   end
     #
-    #   sessions.run("https://wwww.google.com") do |conn|
+    #   sessions.run(url2) do |conn|
     #     p conn.head('/').code
     #   end
     #
     # === OPTIONS
-    # [: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
+    #   [:name]
+    #     A string representing the name of your sessions used for logging.
     #
-    def initialize(opts={},&new_client)
-      raise ArgumentError, "HotTub::Sessions require a block on initialization that accepts a single argument" unless block_given?
-      @close_client     = opts[:close]            # => lambda {|clnt| clnt.close}
-      @clean_client     = opts[:clean]            # => lambda {|clnt| clnt.clean}
-      @reap_client      = opts[:reap]             # => lambda {|clnt| clnt.reap?}  # should return boolean
-      @new_client       = new_client              # => { |url| MyClient.new(url) } # block that accepts a url param
-      @sessions         = ThreadSafe::Cache.new
+    #   [:reaper]
+    #     If set to false prevents a HotTub::Reaper from initializing.
+    #
+    #   [:reap_timeout]
+    #     Default is 600 seconds. An integer that represents the timeout for reaping the pool in seconds.
+    #
+    def initialize(opts={})
+      @name             = (opts[:name] || self.class.name)
+      @reaper           = opts[:reaper]
+      @reap_timeout     = (opts[:reap_timeout] || 600)
+
+      @_sessions        = {}
+      @mutex            = Mutex.new
       @shutdown         = false
-      @reap_timeout     = (opts[:reap_timeout] || 600)      # the interval to reap connections in seconds
-      @reaper           = Reaper.spawn(self) unless opts[:no_reaper]
-      @pool_options     = {:no_reaper => true}.merge(opts)
-      at_exit {drain!}
+
+      at_exit {shutdown!}
+    end
+
+    # Adds a new HotTub::Pool for the given key unless
+    # one already exists.
+    def add(key, pool_options={}, &client_block)
+      raise ArgumentError, 'a block that initializes a new client is required.' unless block_given?
+      pool = nil
+      return pool if pool = @_sessions[key]
+      pool_options[:sessions] = true
+      pool_options[:name] = "#{@name} - #{key}"
+      @mutex.synchronize do
+        @reaper ||= Reaper.spawn(self) if @reaper.nil?
+        pool = @_sessions[key] ||= HotTub::Pool.new(pool_options, &client_block) unless @shutdown
+      end
+      pool
+    end
+
+    # Deletes and shutdowns the pool if its found.
+    def delete(key)
+      deleted = false
+      pool = nil
+      @mutex.synchronize do
+        pool = @_sessions.delete(key)
+      end
+      if pool
+        pool.reset!
+        deleted = true
+        HotTub.logger.info "[HotTub] #{key} was deleted from #{@name}." if HotTub.logger
+      end
+      deleted
     end
 
-    # Safely initializes sessions
-    # expects a url string or URI
-    def session(url)
-      key = to_key(url)
-      return @sessions.get(key) if @sessions.get(key)
-      @sessions.compute_if_absent(key) {
-        HotTub::Pool.new(@pool_options) { @new_client.call(url) }
-      }
-      @sessions.get(key)
+    def fetch(key)
+      pool = @_sessions[key]
+      raise MissingSession, "A session could not be found for #{key.inspect} #{@name}" unless pool
+      pool
     end
-    alias :sessions :session
 
-    def run(url,&block)
-      session = sessions(url)
-      session.run(&block) if session
+    alias :[] :fetch
+
+    def run(url, &run_block)
+      pool = fetch(url)
+      pool.run &run_block
     end
 
     def clean!
-      @sessions.each_pair do |key,pool|
-        pool.clean!
+      HotTub.logger.info "[HotTub] Cleaning #{@name}!" if HotTub.logger
+      @mutex.synchronize do
+        @_sessions.each_value do |pool|
+          break if @shutdown
+          pool.clean!
+        end
       end
-      @sessions
+      nil
     end
 
     def drain!
-      @sessions.each_pair do |key,pool|
-        pool.drain!
+      HotTub.logger.info "[HotTub] Draining #{@name}!" if HotTub.logger
+      @mutex.synchronize do
+        @_sessions.each_value do |pool|
+          break if @shutdown
+          pool.drain!
+        end
       end
-      @sessions
+      nil
     end
 
     def reset!
-      @sessions.each_pair do |key,pool|
-        pool.reset!
+      HotTub.logger.info "[HotTub] Resetting #{@name}!" if HotTub.logger
+      @mutex.synchronize do
+        @_sessions.each_value do |pool|
+          break if @shutdown
+          pool.reset!
+        end
       end
-      @sessions.clear
-      @sessions = ThreadSafe::Cache.new
-      @sessions
+      nil
     end
 
     def shutdown!
       @shutdown = true
+      HotTub.logger.info "[HotTub] Shutting down #{@name}!" if HotTub.logger
       begin
         kill_reaper
       ensure
-        drain!
-        @sessions = nil
+        @mutex.synchronize do
+          @_sessions.each_value do |pool|
+            pool.shutdown!
+          end
+        end
       end
       nil
     end
 
     # Remove and close extra clients
     def reap!
-      @sessions.each_pair do |key,pool|
-        pool.reap!
+      HotTub.logger.info "[HotTub] Reaping #{@name}!" if HotTub.log_trace?
+      @mutex.synchronize do
+        @_sessions.each_value do |pool|
+          break if @shutdown
+          pool.reap!
+        end
       end
+      nil
     end
 
-    private
-
-    def to_key(url)
-      if url.is_a?(String)
-        uri = URI(url)
-      elsif url.is_a?(URI)
-        uri = url
-      else
-        raise ArgumentError, "you must pass a string or a URI object"
-      end
-      "#{uri.scheme}://#{uri.host}:#{uri.port}"
-    end
+    MissingSession = Class.new(Exception)
   end
 end

data/lib/hot_tub/version.rb

@@ -1,3 +1,3 @@
 module HotTub
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end