mongo 2.6.4 → 2.7.0.rc0

data/lib/mongo/server/connection_pool.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -24,6 +24,28 @@ module Mongo
       include Loggable
       extend Forwardable
 
+      # Create the new connection pool.
+      #
+      # @example Create the new connection pool.
+      #   Pool.new(wait_queue_timeout: 0.5) do
+      #     Connection.new
+      #   end
+      #
+      # @note A block must be passed to set up the connections on initialization.
+      #
+      # @param [ Hash ] options The connection pool options.
+      #
+      # @option options [ Integer ] :max_pool_size The maximum pool size.
+      # @option options [ Integer ] :min_pool_size The minimum pool size.
+      # @option options [ Float ] :wait_queue_timeout The time to wait, in
+      #   seconds, for a free connection.
+      #
+      # @since 2.0.0
+      def initialize(options = {}, &block)
+        @options = options.freeze
+        @queue = Queue.new(options, &block)
+      end
+
       # @return [ Hash ] options The pool options.
       attr_reader :options
 
@@ -66,23 +88,6 @@ module Mongo
         queue.disconnect!
       end
 
-      # Create the new connection pool.
-      #
-      # @example Create the new connection pool.
-      #   Pool.new(timeout: 0.5) do
-      #     Connection.new
-      #   end
-      #
-      # @note A block must be passed to set up the connections on initialization.
-      #
-      # @param [ Hash ] options The connection pool options.
-      #
-      # @since 2.0.0
-      def initialize(options = {}, &block)
-        @options = options.freeze
-        @queue = Queue.new(options, &block)
-      end
-
       # Get a pretty printed string inspection for the pool.
       #
       # @example Inspect the pool.
@@ -131,8 +136,8 @@ module Mongo
         #
         # @since 2.0.0
         def get(server)
-          ConnectionPool.new(server.options) do
-            Connection.new(server, server.options)
+          ConnectionPool.new(server.options) do |generation|
+            Connection.new(server, server.options.merge(generation: generation))
           end
         end
       end

data/lib/mongo/server/connection_pool/queue.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -19,22 +19,76 @@ module Mongo
       # A LIFO queue of connections to be used by the connection pool. This is
       # based on mperham's connection pool.
       #
+      # @note The queue contains active connections that are available for
+      #   use. It does not track connections which are in use (checked out).
+      #   It is easy to confuse the size of the connection pool (number of
+      #   connections that are used plus number of connections that are
+      #   available for use) and the size of the queue (number of connections
+      #   that have already been created that are available for use).
+      #   API documentation for this class states whether each size refers
+      #   to the pool or to the queue size. Note that minimum and maximum
+      #   sizes only make sense when talking about the connection pool,
+      #   as the size of the queue of available connections is determined by
+      #   the size constraints of the pool plus how many connections are
+      #   currently checked out.
+      #
       # @since 2.0.0
       class Queue
+        include Loggable
         extend Forwardable
 
-        # Size of the queue delegates to the wrapped queue.
-        def_delegators :queue, :size
-
-        # The default max size for the queue.
+        # The default max size for the connection pool.
         MAX_SIZE = 5.freeze
 
-        # The default min size for the queue.
+        # The default min size for the connection pool.
         MIN_SIZE = 1.freeze
 
         # The default timeout, in seconds, to wait for a connection.
         WAIT_TIMEOUT = 1.freeze
 
+        # Initialize the new queue. Will yield the block the number of times
+        # equal to the initial connection pool size.
+        #
+        # @example Create the queue.
+        #   Mongo::Server::ConnectionPool::Queue.new(max_pool_size: 5) { Connection.new }
+        #
+        # @param [ Hash ] options The options.
+        #
+        # @option options [ Integer ] :max_pool_size The maximum pool size.
+        # @option options [ Integer ] :min_pool_size The minimum pool size.
+        # @option options [ Float ] :wait_queue_timeout The time to wait, in
+        #   seconds, for a free connection.
+        #
+        # @since 2.0.0
+        def initialize(options = {}, &block)
+          if options[:min_pool_size] && options[:max_pool_size] &&
+            options[:min_pool_size] > options[:max_pool_size]
+          then
+            raise ArgumentError, "Cannot have min size > max size"
+          end
+          @block = block
+          # This is the number of connections in the pool.
+          # Includes available connections in the queue and the checked
+          # out connections that we don't otherwise track.
+          @pool_size = 0
+          @options = options
+          @generation = 1
+          if min_size > max_size
+            raise ArgumentError, "min_size (#{min_size}) cannot exceed max_size (#{max_size})"
+          end
+          @queue = Array.new(min_size) { create_connection }
+          @mutex = Mutex.new
+          @resource = ConditionVariable.new
+          check_count_invariants
+        end
+
+        # @return [ Integer ] generation Generation of connections currently
+        #   being used by the queue.
+        #
+        # @since 2.7.0
+        # @api private
+        attr_reader :generation
+
         # @return [ Array ] queue The underlying array of connections.
         attr_reader :queue
 
@@ -47,19 +101,43 @@ module Mongo
         # @return [ ConditionVariable ] resource The resource.
         attr_reader :resource
 
-        # Dequeue a connection from the queue, waiting for the provided timeout
-        # for an item if none is in the queue.
+        # Number of connections that the pool has which are ready to be
+        # checked out. This is NOT the size of the connection pool (total
+        # number of active connections created by the pool).
+        def_delegators :queue, :size
+
+        # Number of connections that the pool has which are ready to be
+        # checked out.
+        #
+        # @since 2.7.0
+        alias_method :queue_size, :size
+
+        # Number of connections in the pool (active connections ready to
+        # be checked out plus connections already checked out).
+        #
+        # @since 2.7.0
+        attr_reader :pool_size
+
+        # Retrieves a connection. If there are active connections in the
+        # queue, the most recently used connection is returned. Otherwise
+        # if the connection pool size is less than the max size, creates a
+        # new connection and returns it. Otherwise raises Timeout::Error.
         #
         # @example Dequeue a connection.
         #   queue.dequeue
         #
         # @return [ Mongo::Server::Connection ] The next connection.
+        # @raise [ Timeout::Error ] If the connection pool is at maximum size
+        #   and remains so for longer than the wait timeout.
         #
         # @since 2.0.0
         def dequeue
+          check_count_invariants
           mutex.synchronize do
             dequeue_connection
           end
+        ensure
+          check_count_invariants
         end
 
         # Disconnect all connections in the queue.
@@ -71,14 +149,40 @@ module Mongo
         #
         # @since 2.1.0
         def disconnect!
+          check_count_invariants
           mutex.synchronize do
             queue.each{ |connection| connection.disconnect! }
+            @pool_size -= queue.length
+            if @pool_size < 0
+              # This should never happen
+              log_warn("ConnectionPool::Queue: connection accounting problem")
+              @pool_size = 0
+            end
+            queue.clear
+            @generation += 1
+            while @pool_size < min_size
+              @pool_size += 1
+              queue.unshift(@block.call(@generation))
+            end
             true
           end
+        ensure
+          check_count_invariants
         end
 
         # Enqueue a connection in the queue.
         #
+        # Only connections created by this queue should be enqueued
+        # back into it, however the queue does not verify whether it
+        # originally created the connection being enqueued.
+        #
+        # If linting is enabled (see Mongo::Lint), attempting to enqueue
+        # connections beyond the pool's capacity will raise Mongo::Error::LintError
+        # (since some of those connections must not have originated from
+        # the queue into which they are being enqueued). If linting is
+        # not enabled, the queue can grow beyond its max size with undefined
+        # results.
+        #
         # @example Enqueue a connection.
         #   queue.enqueue(connection)
         #
@@ -86,33 +190,31 @@ module Mongo
         #
         # @since 2.0.0
         def enqueue(connection)
+          check_count_invariants
           mutex.synchronize do
-            queue.unshift(connection.record_checkin!)
-            resource.broadcast
-          end
-        end
+            if connection.generation == @generation
+              queue.unshift(connection.record_checkin!)
+              resource.broadcast
+            else
+              connection.disconnect!
 
-        # Initialize the new queue. Will yield the block the number of times for
-        # the initial size of the queue.
-        #
-        # @example Create the queue.
-        #   Mongo::Server::ConnectionPool::Queue.new(max_pool_size: 5) { Connection.new }
-        #
-        # @param [ Hash ] options The options.
-        #
-        # @option options [ Integer ] :max_pool_size The maximum size.
-        # @option options [ Integer ] :min_pool_size The minimum size.
-        # @option options [ Float ] :wait_queue_timeout The time to wait, in
-        #   seconds, for a free connection.
-        #
-        # @since 2.0.0
-        def initialize(options = {}, &block)
-          @block = block
-          @connections = 0
-          @options = options
-          @queue = Array.new(min_size) { create_connection }
-          @mutex = Mutex.new
-          @resource = ConditionVariable.new
+              @pool_size = if @pool_size > 0
+                @pool_size - 1
+              else
+                # This should never happen
+                log_warn("ConnectionPool::Queue: unexpected enqueue")
+                0
+              end
+
+              while @pool_size < min_size
+                @pool_size += 1
+                queue.unshift(@block.call(@generation))
+              end
+            end
+          end
+          nil
+        ensure
+          check_count_invariants
         end
 
         # Get a pretty printed string inspection for the queue.
@@ -125,27 +227,27 @@ module Mongo
         # @since 2.0.0
         def inspect
           "#<Mongo::Server::ConnectionPool::Queue:0x#{object_id} min_size=#{min_size} max_size=#{max_size} " +
-            "wait_timeout=#{wait_timeout} current_size=#{queue.size}>"
+            "wait_timeout=#{wait_timeout} current_size=#{queue_size}>"
         end
 
-        # Get the maximum size of the queue.
+        # Get the maximum size of the connection pool.
         #
         # @example Get the max size.
         #   queue.max_size
         #
-        # @return [ Integer ] The maximum size of the queue.
+        # @return [ Integer ] The maximum size of the connection pool.
         #
         # @since 2.0.0
         def max_size
-          @max_size ||= options[:max_pool_size] || MAX_SIZE
+          @max_size ||= options[:max_pool_size] || [MAX_SIZE, min_size].max
         end
 
-        # Get the minimum size of the queue.
+        # Get the minimum size of the connection pool.
         #
         # @example Get the min size.
         #   queue.min_size
         #
-        # @return [ Integer ] The minimum size of the queue.
+        # @return [ Integer ] The minimum size of the connection pool.
         #
         # @since 2.0.0
         def min_size
@@ -164,7 +266,8 @@ module Mongo
           @wait_timeout ||= options[:wait_queue_timeout] || WAIT_TIMEOUT
         end
 
-        # The maximum seconds a socket can remain idle since it has been checked in to the pool.
+        # The maximum seconds a socket can remain idle since it has been
+        # checked in to the pool.
         #
         # @example Get the max idle time.
         #   queue.max_idle_time
@@ -176,14 +279,15 @@ module Mongo
           @max_idle_time ||= options[:max_idle_time]
         end
 
-        # Close sockets that have been open for longer than the max idle time, if the
-        #   option is set.
+        # Close sockets that have been open for longer than the max idle time,
+        #   if the option is set.
         #
         # @example Close the stale sockets
         #   queue.close_stale_sockets!
         #
         # @since 2.5.0
         def close_stale_sockets!
+          check_count_invariants
           return unless max_idle_time
 
           to_refresh = []
@@ -196,7 +300,7 @@ module Mongo
           end
 
           mutex.synchronize do
-            num_checked_out = @connections - queue.size
+            num_checked_out = pool_size - queue_size
             min_size_delta = [(min_size - num_checked_out), 0].max
 
             to_refresh.each do |connection|
@@ -208,6 +312,8 @@ module Mongo
               end
             end
           end
+        ensure
+          check_count_invariants
         end
 
         private
@@ -223,9 +329,9 @@ module Mongo
         end
 
         def create_connection
-          if @connections < max_size
-            @connections += 1
-            @block.call
+          if pool_size < max_size
+            @pool_size += 1
+            @block.call(@generation)
           end
         end
 
@@ -236,6 +342,17 @@ module Mongo
           end
           resource.wait(mutex, wait)
         end
+
+        def check_count_invariants
+          if Mongo::Lint.enabled?
+            if pool_size < min_size
+              raise Error::LintError, 'connection pool queue: underflow'
+            end
+            if pool_size > max_size
+              raise Error::LintError, 'connection pool queue: overflow'
+            end
+          end
+        end
       end
     end
   end

data/lib/mongo/server/context.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the 'License');
 # you may not use this file except in compliance with the License.
@@ -24,6 +24,18 @@ module Mongo
     class Context
       extend Forwardable
 
+      # Instantiate a server context.
+      #
+      # @example Instantiate a server context.
+      #   Mongo::Server::Context.new(server)
+      #
+      # @param [ Mongo::Server ] server The server the context is for.
+      #
+      # @since 2.0.0
+      def initialize(server)
+        @server = server
+      end
+
       # @return [ Mongo::Server ] server The server the context is for.
       attr_reader :server
 
@@ -38,18 +50,6 @@ module Mongo
                      :secondary?,
                      :standalone?
 
-      # Instantiate a server context.
-      #
-      # @example Instantiate a server context.
-      #   Mongo::Server::Context.new(server)
-      #
-      # @param [ Mongo::Server ] server The server the context is for.
-      #
-      # @since 2.0.0
-      def initialize(server)
-        @server = server
-      end
-
       # Execute a block of code with a connection, that is checked out of the
       # pool and then checked back in.
       #

data/lib/mongo/server/description.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2014-2018 MongoDB, Inc.
+# Copyright (C) 2014-2019 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the 'License');
 # you may not use this file except in compliance with the License.
@@ -13,7 +13,6 @@
 # limitations under the License.
 
 require 'mongo/server/description/features'
-require 'mongo/server/description/inspector'
 
 module Mongo
   class Server
@@ -107,6 +106,7 @@ module Mongo
       # The legacy wire protocol version.
       #
       # @since 2.0.0
+      # @deprecated Will be removed in 3.0.
       LEGACY_WIRE_VERSION = 0.freeze
 
       # Constant for reading passive info from config.
@@ -177,6 +177,37 @@ module Mongo
                                  OPERATION_TIME,
                                  Operation::CLUSTER_TIME ].freeze
 
+      # Instantiate the new server description from the result of the ismaster
+      # command.
+      #
+      # @example Instantiate the new description.
+      #   Description.new(address, { 'ismaster' => true }, 0.5)
+      #
+      # @param [ Address ] address The server address.
+      # @param [ Hash ] config The result of the ismaster command.
+      # @param [ Float ] average_round_trip_time The moving average time (sec) the ismaster
+      #   call took to complete.
+      #
+      # @since 2.0.0
+      def initialize(address, config = {}, average_round_trip_time = nil)
+        @address = address
+        @config = config
+        unless unknown?
+          @features = Features.new(wire_versions, me || @address.to_s)
+        end
+        @average_round_trip_time = average_round_trip_time
+        @last_update_time = Time.now.freeze
+
+        if Mongo::Lint.enabled?
+          # prepopulate cache instance variables
+          hosts
+          arbiters
+          passives
+
+          freeze
+        end
+      end
+
       # @return [ Address ] address The server's address.
       attr_reader :address
 
@@ -184,7 +215,12 @@ module Mongo
       attr_reader :config
 
       # @return [ Features ] features The features for the server.
-      attr_reader :features
+      def features
+        if unknown?
+          raise ArgumentError, "An unknown server's features are not known"
+        end
+        @features
+      end
 
       # @return [ Float ] The moving average time the ismaster call took to complete.
       attr_reader :average_round_trip_time
@@ -198,7 +234,7 @@ module Mongo
       #
       # @since 2.0.0
       def arbiter?
-        !!config[ARBITER] && !replica_set_name.nil?
+        ok? && !!config[ARBITER] && !replica_set_name.nil?
       end
 
       # Get a list of all arbiters in the replica set.
@@ -222,7 +258,7 @@ module Mongo
       #
       # @since 2.0.0
       def ghost?
-        !!config[REPLICA_SET]
+        ok? && !!config[REPLICA_SET]
       end
 
       # Will return true if the server is hidden.
@@ -234,7 +270,7 @@ module Mongo
       #
       # @since 2.0.0
       def hidden?
-        !!config[HIDDEN]
+        ok? && !!config[HIDDEN]
       end
 
       # Get a list of all servers in the replica set.
@@ -249,25 +285,6 @@ module Mongo
         @hosts ||= (config[HOSTS] || []).map { |s| s.downcase }
       end
 
-      # Instantiate the new server description from the result of the ismaster
-      # command.
-      #
-      # @example Instantiate the new description.
-      #   Description.new(address, { 'ismaster' => true }, 0.5)
-      #
-      # @param [ Address ] address The server address.
-      # @param [ Hash ] config The result of the ismaster command.
-      # @param [ Float ] average_round_trip_time The moving average time (sec) the ismaster
-      #   call took to complete.
-      #
-      # @since 2.0.0
-      def initialize(address, config = {}, average_round_trip_time = 0)
-        @address = address
-        @config = config
-        @features = Features.new(wire_versions, me || @address.to_s)
-        @average_round_trip_time = average_round_trip_time
-      end
-
       # Inspect the server description.
       #
       # @example Inspect the server description
@@ -325,7 +342,7 @@ module Mongo
       #
       # @since 2.0.0
       def max_wire_version
-        config[MAX_WIRE_VERSION] || LEGACY_WIRE_VERSION
+        config[MAX_WIRE_VERSION]
       end
 
       # Get the minimum wire version.
@@ -337,7 +354,7 @@ module Mongo
       #
       # @since 2.0.0
       def min_wire_version
-        config[MIN_WIRE_VERSION] || LEGACY_WIRE_VERSION
+        config[MIN_WIRE_VERSION]
       end
 
       # Get the me field value.
@@ -421,7 +438,7 @@ module Mongo
       #
       # @since 2.0.0
       def mongos?
-        config[MESSAGE] == MONGOS_MESSAGE
+        ok? && config[MESSAGE] == MONGOS_MESSAGE
       end
 
       # Is the description of type other.
@@ -433,6 +450,12 @@ module Mongo
       #
       # @since 2.0.0
       def other?
+        # The SDAM spec is slightly confusing on what "other" means,
+        # but it's referred to it as "RSOther" which means a non-RS member
+        # cannot be "other".
+        if unknown? || replica_set_name.nil?
+          return false
+        end
         (!primary? && !secondary? && !passive? && !arbiter?) ||
           (hidden? && !replica_set_name.nil?)
       end
@@ -446,7 +469,7 @@ module Mongo
       #
       # @since 2.0.0
       def passive?
-        !!config[PASSIVE]
+        ok? && !!config[PASSIVE]
       end
 
       # Get a list of the passive servers in the cluster.
@@ -482,9 +505,10 @@ module Mongo
       #
       # @since 2.0.0
       def primary?
-        !!config[PRIMARY] &&
+        ok? &&
+          !!config[PRIMARY] &&
           (primary_host.nil? || primary_host == address.to_s) &&
-            !replica_set_name.nil?
+          !replica_set_name.nil?
       end
 
       # Get the name of the replica set the server belongs to, returns nil if
@@ -521,7 +545,7 @@ module Mongo
       #
       # @since 2.0.0
       def secondary?
-        !!config[SECONDARY] && !replica_set_name.nil?
+        ok? && !!config[SECONDARY] && !replica_set_name.nil?
       end
 
       # Returns the server type as a symbol.
@@ -539,6 +563,7 @@ module Mongo
         return :primary if primary?
         return :secondary if secondary?
         return :standalone if standalone?
+        return :other if other?
         :unknown
       end
 
@@ -563,22 +588,13 @@ module Mongo
       #
       # @since 2.0.0
       def unknown?
-        config.empty? || (config[Operation::Result::OK] &&
-                            config[Operation::Result::OK] != 1)
+        config.empty? || !ok?
       end
 
-      # A result from another server's ismaster command before this server has
-      # refreshed causes the need for this description to become unknown before
-      # the next refresh.
-      #
-      # @example Force an unknown state.
-      #   description.unknown!
-      #
-      # @return [ true ] Always true.
-      #
-      # @since 2.0.0
-      def unknown!
-        @config = {} and true
+      # @api private
+      def ok?
+        config[Operation::Result::OK] &&
+          config[Operation::Result::OK] == 1 || false
       end
 
       # Get the range of supported wire versions for the server.
@@ -628,7 +644,18 @@ module Mongo
       #
       # @since 2.0.6
       def replica_set_member?
-        !(standalone? || mongos?)
+        ok? && !(standalone? || mongos?)
+      end
+
+      # Whether this description is from a data-bearing server
+      # (standalone, mongos, primary or secondary).
+      #
+      # @return [ true, false ] Whether the description is from a data-bearing
+      #   server.
+      #
+      # @since 2.7.0
+      def data_bearing?
+        mongos? || primary? || secondary? || standalone?
       end
 
       # Check if there is a mismatch between the address host and the me field.
@@ -643,6 +670,24 @@ module Mongo
         !!(address.to_s.downcase != me.downcase if me)
       end
 
+      # opTime in lastWrite subdocument of the ismaster response.
+      #
+      # @return [ BSON::Timestamp ] The timestamp.
+      #
+      # @since 2.7.0
+      def op_time
+        if config['lastWrite'] && config['lastWrite']['opTime']
+          config['lastWrite']['opTime']['ts']
+        end
+      end
+
+      # Time when the server was last checked.
+      #
+      # @return [ Time ] Last check time.
+      #
+      # @since 2.7.0
+      attr_reader :last_update_time
+
       # Check equality of two descriptions.
       #
       # @example Check description equality.
@@ -663,7 +708,7 @@ module Mongo
       private
 
       def compare_config(other)
-        config.keys.all? do |k|
+        (config.keys + other.config.keys).uniq.all? do |k|
           config[k] == other.config[k] || EXCLUDE_FOR_COMPARISON.include?(k)
         end
       end