activerecord-bogacs 0.5.0 → 0.7.0

data/lib/active_record/bogacs/default_pool.rb

@@ -1,5 +1,8 @@
+require 'active_record/version'
+
 require 'thread'
 require 'monitor'
+require 'concurrent/atomic/atomic_boolean'
 
 require 'active_record/connection_adapters/adapter_compat'
 require 'active_record/bogacs/pool_support'
@@ -8,49 +11,17 @@ require 'active_record/bogacs/thread_safe'
 module ActiveRecord
   module Bogacs
 
-    # == Obtaining (checking out) a connection
-    #
-    # Connections can be obtained and used from a connection pool in several
-    # ways:
-    #
-    # 1. Simply use ActiveRecord::Base.connection as with Active Record 2.1 and
-    # earlier (pre-connection-pooling). Eventually, when you're done with
-    # the connection(s) and wish it to be returned to the pool, you call
-    # ActiveRecord::Base.clear_active_connections!.
-    # 2. Manually check out a connection from the pool with
-    # ActiveRecord::Base.connection_pool.checkout. You are responsible for
-    # returning this connection to the pool when finished by calling
-    # ActiveRecord::Base.connection_pool.checkin(connection).
-    # 3. Use ActiveRecord::Base.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 are actually AbstractAdapter objects (or objects
-    # compatible with AbstractAdapter's interface).
+    # A "default" `ActiveRecord::ConnectionAdapters::ConnectionPool`-like pool
+    # implementation with compatibility across (older) Rails versions.
     #
-    # == Options
+    # Currently, mostly, based on ActiveRecord **4.2**.
     #
-    # There are several connection-pooling-related options that you can add to
-    # your database connection configuration:
+    # http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/ConnectionPool.html
     #
-    # * **pool**: number indicating size of connection pool (default 5)
-    # * **checkout_timeout**: number of seconds to block and wait for a connection
-    # before giving up and raising a timeout error (default 5 seconds).
-    # * **pool_initial**: number of connections to pre-initialize when the pool
-    # is created (default 0).
-    # * **reaping_frequency**: frequency in seconds to periodically run a reaper,
-    # which attempts to find and close "dead" connections (can occur if a caller
-    # forgets to close a connection at the end of a thread or a thread dies unexpectedly)
-    # Default is `nil`, which means don't run the periodical Reaper at all (reaping
-    # will still happen occasionally).
     class DefaultPool
-      # Threadsafe, fair, FIFO queue. Meant to be used by ConnectionPool
-      # with which it shares a Monitor. But could be a generic Queue.
-      #
-      # The Queue in stdlib's 'thread' could replace this class except
-      # stdlib's doesn't support waiting with a timeout.
+
       # @private
-      class Queue
+      class Queue # ConnectionLeasingQueue
         def initialize(lock)
           @lock = lock
           @cond = @lock.new_cond
@@ -106,21 +77,27 @@ module ActiveRecord
         # available, waiting up to +timeout+ seconds for an element to
         # become available.
         #
-        # Raises:
-        # - ConnectionTimeoutError if +timeout+ is given and no element
-        # becomes available after +timeout+ seconds,
-        def poll(timeout = nil, &block)
-          synchronize do
-            if timeout
-              no_wait_poll || wait_poll(timeout, &block)
-            else
-              no_wait_poll
-            end
-          end
+        # @raise [ActiveRecord::ConnectionTimeoutError] if +timeout+ given and no element
+        # becomes available after +timeout+ seconds
+        def poll(timeout = nil)
+          synchronize { internal_poll(timeout) }
         end
 
         private
 
+        def internal_poll(timeout)
+          conn = no_wait_poll || (timeout && wait_poll(timeout))
+          # Connections must be leased while holding the main pool mutex. This is
+          # an internal subclass that also +.leases+ returned connections while
+          # still in queue's critical section (queue synchronizes with the same
+          # <tt>@lock</tt> as the main pool) so that a returned connection is already
+          # leased and there is no need to re-enter synchronized block.
+          #
+          # NOTE: avoid the need for ConnectionLeasingQueue, since BiasableQueue is not implemented
+          conn.lease if conn
+          conn
+        end
+
         def synchronize(&block)
           @lock.synchronize(&block)
         end
@@ -131,21 +108,21 @@ module ActiveRecord
         end
 
         # A thread can remove an element from the queue without
-        # waiting if an only if the number of currently available
+        # waiting if and only if the number of currently available
         # connections is strictly greater than the number of waiting
         # threads.
         def can_remove_no_wait?
           @queue.size > @num_waiting
         end
 
-        # Removes and returns the head of the queue if possible, or nil.
+        # Removes and returns the head of the queue if possible, or +nil+.
         def remove
-          @queue.shift
+          @queue.pop
         end
 
         # Remove and return the head the queue if the number of
         # available elements is strictly greater than the number of
-        # threads currently waiting. Otherwise, return nil.
+        # threads currently waiting.  Otherwise, return +nil+.
         def no_wait_poll
           remove if can_remove_no_wait?
         end
@@ -153,13 +130,10 @@ module ActiveRecord
         # Waits on the queue up to +timeout+ seconds, then removes and
         # returns the head of the queue.
         def wait_poll(timeout)
-          t0 = Time.now
-          elapsed = 0
-
           @num_waiting += 1
 
-          yield if block_given?
-
+          t0 = Time.now
+          elapsed = 0
           while true
             @cond.wait(timeout - elapsed)
 
@@ -183,22 +157,42 @@ module ActiveRecord
       require 'active_record/bogacs/reaper.rb'
 
       attr_accessor :automatic_reconnect, :checkout_timeout
-      attr_reader :spec, :connections, :size, :reaper, :validator
-      attr_reader :initial_size
+      attr_reader :spec, :size, :reaper
+      attr_reader :validator, :initial_size
 
-      # Creates a new ConnectionPool object. +spec+ is a ConnectionSpecification
+      # 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.
+      # @note The default ConnectionPool maximum size is **5**.
+      #
+      # @param [Hash] spec a `ConnectionSpecification`
+      #
+      # @option spec.config [Integer] :pool number indicating size of connection pool (default 5)
+      # @option spec.config [Float] :checkout_timeout number of seconds to block and
+      # wait for a connection before giving up raising a timeout (default 5 seconds).
+      # @option spec.config [Integer] :pool_initial number of connections to pre-initialize
+      # when the pool is created (default 0).
+      # @option spec.config [Float] :reaping_frequency frequency in seconds to periodically
+      # run a reaper, which attempts to find and close "dead" connections (can occur
+      # if a caller forgets to close a connection at the end of a thread or a thread
+      # dies unexpectedly) default is `nil` - don't run the periodical Reaper (reaping
+      # will still happen occasionally).
+      # @option spec.config [Float] :validate_frequency frequency in seconds to periodically
+      # run a connection validation (in a separate thread), to avoid potentially stale
+      # sockets when connections stay open (pooled but unused) for longer periods.
       def initialize(spec)
         super()
 
         @spec = spec
 
-        @checkout_timeout = ( spec.config[:checkout_timeout] ||
-            spec.config[:wait_timeout] || 5.0 ).to_f # <= 3.2 supports wait_timeout
+        @checkout_timeout = ( spec.config[:checkout_timeout] || 5 ).to_f
+        if @idle_timeout = spec.config.fetch(:idle_timeout, 300)
+          @idle_timeout = @idle_timeout.to_f
+          @idle_timeout = nil if @idle_timeout <= 0
+        end
+
         @reaper = Reaper.new self, spec.config[:reaping_frequency]
         @reaping = !! @reaper.run
 
@@ -213,13 +207,24 @@ module ActiveRecord
         end
 
         # The cache of reserved connections mapped to threads
-        @reserved_connections = ThreadSafe::Map.new(:initial_capacity => @size)
+        @thread_cached_conns = ThreadSafe::Map.new(initial_capacity: @size)
 
         @connections = []
         @automatic_reconnect = true
 
+        # Connection pool allows for concurrent (outside the main +synchronize+ section)
+        # establishment of new connections. This variable tracks the number of threads
+        # currently in the process of independently establishing connections to the DB.
+        @now_connecting = 0
+
+        @threads_blocking_new_connections = 0 # TODO: dummy for now
+
         @available = Queue.new self
 
+        @lock_thread = false
+
+        @connected = ::Concurrent::AtomicBoolean.new
+
         initial_size = spec.config[:pool_initial] || 0
         initial_size = @size if initial_size == true
         initial_size = (@size * initial_size).to_i if initial_size <= 1.0
@@ -230,7 +235,7 @@ module ActiveRecord
           require 'active_record/bogacs/validator' unless self.class.const_defined?(:Validator)
           @validator = Validator.new self, frequency, spec.config[:validate_timeout]
           if @validator.run && @reaping
-            logger && logger.info("pool: validator configured alongside with reaper")
+            logger && logger.warn(":validate_frequency configured alongside with :reaping_frequency")
           end
         end
       end
@@ -243,12 +248,9 @@ module ActiveRecord
       #
       # @return [ActiveRecord::ConnectionAdapters::AbstractAdapter]
       def connection
-        connection_id = current_connection_id
-        unless conn = @reserved_connections.fetch(connection_id, nil)
-          synchronize do
-            conn = ( @reserved_connections[connection_id] ||= checkout )
-          end
-        end
+        connection_id = current_connection_id(current_thread)
+        conn = @thread_cached_conns.fetch(connection_id, nil)
+        conn = ( @thread_cached_conns[connection_id] ||= checkout ) unless conn
         conn
       end
 
@@ -256,22 +258,16 @@ module ActiveRecord
       #
       # @return [true, false]
       def active_connection?
-        connection_id = current_connection_id
-        if conn = @reserved_connections.fetch(connection_id, nil)
-          !! conn.in_use? # synchronize { conn.in_use? }
-        else
-          false
-        end
+        connection_id = current_connection_id(current_thread)
+        @thread_cached_conns.fetch(connection_id, nil)
       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(with_id = current_connection_id)
-        #synchronize do
-          conn = @reserved_connections.delete(with_id)
-          checkin conn, true if conn
-        #end
+      def release_connection(owner_thread = Thread.current)
+        conn = @thread_cached_conns.delete(current_connection_id(owner_thread))
+        checkin conn if conn
       end
 
       # If a connection already exists yield it to the block. If no connection
@@ -281,25 +277,48 @@ module ActiveRecord
       # @yield [ActiveRecord::ConnectionAdapters::AbstractAdapter]
       def with_connection
         connection_id = current_connection_id
-        fresh_connection = true unless active_connection?
-        yield connection
+        unless conn = @thread_cached_conns[connection_id]
+          conn = connection
+          fresh_connection = true
+        end
+        yield conn
       ensure
-        release_connection(connection_id) if fresh_connection
+        release_connection if fresh_connection
       end
 
       # Returns true if a connection has already been opened.
       #
       # @return [true, false]
       def connected?
-        @connections.size > 0 # synchronize { @connections.any? }
+        @connected.true? # synchronize { @connections.any? }
+      end
+
+      # Returns an array containing the connections currently in the pool.
+      # Access to the array does not require synchronization on the pool because
+      # the array is newly created and not retained by the pool.
+      #
+      # However; this method bypasses the ConnectionPool's thread-safe connection
+      # access pattern. A returned connection may be owned by another thread,
+      # unowned, or by happen-stance owned by the calling thread.
+      #
+      # Calling methods on a connection without ownership is subject to the
+      # thread-safety guarantees of the underlying method. Many of the methods
+      # on connection adapter classes are inherently multi-thread unsafe.
+      def connections
+        synchronize { @connections.dup }
       end
 
       # Disconnects all connections in the pool, and clears the pool.
       def disconnect!
         synchronize do
-          @reserved_connections.clear
+          @connected.make_false
+
+          @thread_cached_conns.clear
           @connections.each do |conn|
-            checkin conn
+            if conn.in_use?
+              conn.steal!
+              checkin conn
+            end
             conn.disconnect!
           end
           @connections.clear
@@ -307,21 +326,39 @@ module ActiveRecord
         end
       end
 
-      # Clears the cache which maps classes.
+      # Discards all connections in the pool (even if they're currently
+      # leased!), along with the pool itself. Any further interaction with the
+      # pool (except #spec and #schema_cache) is undefined.
+      #
+      # See AbstractAdapter#discard!
+      def discard! # :nodoc:
+        synchronize do
+          return if @connections.nil? # already discarded
+          @connected.make_false
+
+          @connections.each do |conn|
+            conn.discard!
+          end
+          @connections = @available = @thread_cached_conns = nil
+        end
+      end
       def clear_reloadable_connections!
         synchronize do
-          @reserved_connections.clear
+          @thread_cached_conns.clear
           @connections.each do |conn|
-            checkin conn
+            if conn.in_use?
+              conn.steal!
+              checkin conn
+            end
             conn.disconnect! if conn.requires_reloading?
           end
-          @connections.delete_if do |conn|
-            conn.requires_reloading?
-          end
+          @connections.delete_if(&:requires_reloading?)
           @available.clear
           @connections.each do |conn|
             @available.add conn
           end
+
+          @connected.value = @connections.any?
         end
       end
 
@@ -342,11 +379,11 @@ module ActiveRecord
       # @private AR 3.2 compatibility
       def clear_stale_cached_connections!
         keys = Thread.list.find_all { |t| t.alive? }.map(&:object_id)
-        keys = @reserved_connections.keys - keys
+        keys = @thread_cached_conns.keys - keys
         keys.each do |key|
-          conn = @reserved_connections[key]
+          conn = @thread_cached_conns[key]
           checkin conn
-          @reserved_connections.delete(key)
+          @thread_cached_conns.delete(key)
         end
       end if ActiveRecord::VERSION::MAJOR < 4
 
@@ -361,28 +398,25 @@ module ActiveRecord
       # @raise [ActiveRecord::ConnectionTimeoutError] if all connections are leased
       # and the pool is at capacity (meaning the number of currently leased
       # connections is greater than or equal to the size limit set)
-      def checkout
-        conn = nil
-        synchronize do
-          conn = acquire_connection
-          conn.lease
-        end
-        checkout_and_verify(conn)
+      def checkout(checkout_timeout = @checkout_timeout)
+        checkout_and_verify(acquire_connection(checkout_timeout))
       end
 
-      # Check-in a database connection back into the pool.
+      # Check-in a database connection back into the pool, indicating that you
+      # no longer need this connection.
       #
-      # @param [ActiveRecord::ConnectionAdapters::AbstractAdapter] connection
-      # object, which was obtained earlier by calling #checkout on this pool
-      # @see #checkout
-      def checkin(conn, released = nil)
+      # +conn+: an AbstractAdapter object, which was obtained by earlier by
+      # calling #checkout on this pool.
+      def checkin(conn)
+        #conn.lock.synchronize do
         synchronize do
-          _run_checkin_callbacks(conn)
+          remove_connection_from_thread_cache conn
 
-          release conn, conn.owner unless released
+          _run_checkin_callbacks(conn)
 
           @available.add conn
         end
+        #end
       end
 
       # Remove a connection from the connection pool. The returned connection
@@ -390,14 +424,25 @@ module ActiveRecord
       #
       # @return [ActiveRecord::ConnectionAdapters::AbstractAdapter]
       def remove(conn)
+        needs_new_connection = false
+
         synchronize do
+          remove_connection_from_thread_cache conn
+
           @connections.delete conn
           @available.delete conn
 
-          release conn, conn.owner
+          @connected.value = @connections.any?
 
-          @available.add checkout_new_connection if @available.any_waiting?
+          needs_new_connection = @available.any_waiting?
         end
+
+        # This is intentionally done outside of the synchronized section as we
+        # would like not to hold the main mutex while checking out new connections.
+        # Thus there is some chance that needs_new_connection information is now
+        # stale, we can live with that (bulk_make_new_connections will make
+        # sure not to exceed the pool's @size limit).
+        bulk_make_new_connections(1) if needs_new_connection
       end
 
       # Recover lost connections for the pool. A lost connection can occur if
@@ -407,6 +452,8 @@ module ActiveRecord
         stale_connections = synchronize do
           @connections.select do |conn|
             conn.in_use? && !conn.owner.alive?
+          end.each do |conn|
+            conn.steal!
           end
         end
 
@@ -421,6 +468,61 @@ module ActiveRecord
           end
         end
       end
+
+      # Disconnect all connections that have been idle for at least
+      # +minimum_idle+ seconds. Connections currently checked out, or that were
+      # checked in less than +minimum_idle+ seconds ago, are unaffected.
+      def flush(minimum_idle = @idle_timeout)
+        return if minimum_idle.nil?
+
+        idle_connections = synchronize do
+          @connections.select do |conn|
+            !conn.in_use? && conn.seconds_idle >= minimum_idle
+          end.each do |conn|
+            conn.lease
+
+            @available.delete conn
+            @connections.delete conn
+
+            @connected.value = @connections.any?
+          end
+        end
+
+        idle_connections.each do |conn|
+          conn.disconnect!
+        end
+      end
+
+      # Disconnect all currently idle connections. Connections currently checked
+      # out are unaffected.
+      def flush!
+        reap
+        flush(-1)
+      end
+
+      def num_waiting_in_queue # :nodoc:
+        @available.num_waiting
+      end
+      private :num_waiting_in_queue
+
+      # Return connection pool's usage statistic
+      # Example:
+      #
+      #    ActiveRecord::Base.connection_pool.stat # => { size: 15, connections: 1, busy: 1, dead: 0, idle: 0, waiting: 0, checkout_timeout: 5 }
+      def stat
+        synchronize do
+          {
+            size: size,
+            connections: @connections.size,
+            busy: @connections.count { |c| c.in_use? && c.owner.alive? },
+            dead: @connections.count { |c| c.in_use? && !c.owner.alive? },
+            idle: @connections.count { |c| !c.in_use? },
+            waiting: num_waiting_in_queue,
+            checkout_timeout: checkout_timeout
+          }
+        end
+      end
+
       # NOTE: active? and reset! are >= AR 2.3
 
       def reaper?; (@reaper ||= nil) && @reaper.frequency end
@@ -435,43 +537,90 @@ module ActiveRecord
 
       private
 
+      def bulk_make_new_connections(num_new_conns_needed)
+        num_new_conns_needed.times do
+          # try_to_checkout_new_connection will not exceed pool's @size limit
+          if new_conn = try_to_checkout_new_connection
+            # make the new_conn available to the starving threads stuck @available Queue
+            checkin(new_conn)
+          end
+        end
+      end
+
       # Acquire a connection by one of 1) immediately removing one
       # from the queue of available connections, 2) creating a new
       # connection if the pool is not at capacity, 3) waiting on the
       # queue for a connection to become available.
       #
-      # Raises:
-      # - ConnectionTimeoutError if a connection could not be acquired
-      def acquire_connection
-        if conn = @available.poll
+      # @raise [ActiveRecord::ConnectionTimeoutError]
+      # @raise [ActiveRecord::ConnectionNotEstablished]
+      def acquire_connection(checkout_timeout)
+        if conn = @available.poll || try_to_checkout_new_connection
           conn
-        elsif @connections.size < @size
-          checkout_new_connection
         else
           reap unless @reaping
-          @available.poll(@checkout_timeout)
+          @available.poll(checkout_timeout)
         end
       end
 
-      def release(conn, owner)
-        thread_id = owner.object_id
-        if @reserved_connections[thread_id] == conn
-          @reserved_connections.delete thread_id
+      #--
+      # if owner_thread param is omitted, this must be called in synchronize block
+      def remove_connection_from_thread_cache(conn, owner_thread = conn.owner)
+        @thread_cached_conns.delete_pair(current_connection_id(owner_thread), conn)
+      end
+      alias_method :release, :remove_connection_from_thread_cache
+
+      # If the pool is not at a <tt>@size</tt> limit, establish new connection. Connecting
+      # to the DB is done outside main synchronized section.
+      #--
+      # Implementation constraint: a newly established connection returned by this
+      # method must be in the +.leased+ state.
+      def try_to_checkout_new_connection
+        # first in synchronized section check if establishing new conns is allowed
+        # and increment @now_connecting, to prevent overstepping this pool's @size
+        # constraint
+        do_checkout = synchronize do
+          if @threads_blocking_new_connections.zero? && (@connections.size + @now_connecting) < @size
+            @now_connecting += 1
+          end
+        end
+        if do_checkout
+          begin
+            # if successfully incremented @now_connecting establish new connection
+            # outside of synchronized section
+            conn = checkout_new_connection
+          ensure
+            synchronize do
+              if conn
+                adopt_connection(conn)
+                # returned conn needs to be already leased
+                conn.lease
+              end
+              @now_connecting -= 1
+            end
+          end
         end
       end
 
+      def adopt_connection(conn)
+        conn.pool = self
+        @connections << conn
+      end
+
       def checkout_new_connection
         raise ConnectionNotEstablished unless @automatic_reconnect
-
         conn = new_connection
-        conn.pool = self
-        @connections << conn
+        @connected.make_true
         conn
       end
 
       def checkout_and_verify(conn)
         _run_checkout_callbacks(conn)
         conn
+      rescue => e
+        remove conn
+        conn.disconnect!
+        raise e
       end
 
       def prefill_initial_connections
@@ -488,4 +637,4 @@ module ActiveRecord
     end
 
   end
-end
+end