mongo 2.23.0 → 2.24.1

data/lib/mongo/server/connection_pool.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 # Copyright (C) 2014-2020 MongoDB Inc.
 #
@@ -17,7 +16,6 @@
 
 module Mongo
   class Server
-
     # Represents a connection pool for server connections.
     #
     # @since 2.0.0, largely rewritten in 2.9.0
@@ -52,7 +50,7 @@ module Mongo
       # thus anything over 15 seconds is potentially dangerous.
       #
       # @since 2.9.0
-      DEFAULT_WAIT_TIMEOUT = 10.freeze
+      DEFAULT_WAIT_TIMEOUT = 10
 
       # Condition variable broadcast when the size of the pool changes
       # to wake up the populator
@@ -100,31 +98,32 @@ module Mongo
       # @since 2.0.0, API changed in 2.9.0
 
       def initialize(server, options = {})
-        unless server.is_a?(Server)
-          raise ArgumentError, 'First argument must be a Server instance'
-        end
+        raise ArgumentError, 'First argument must be a Server instance' unless server.is_a?(Server)
+
         options = options.dup
         if options[:min_size] && options[:min_pool_size] && options[:min_size] != options[:min_pool_size]
-          raise ArgumentError, "Min size #{options[:min_size]} is not identical to min pool size #{options[:min_pool_size]}"
+          raise ArgumentError,
+                "Min size #{options[:min_size]} is not identical to min pool size #{options[:min_pool_size]}"
         end
         if options[:max_size] && options[:max_pool_size] && options[:max_size] != options[:max_pool_size]
-          raise ArgumentError, "Max size #{options[:max_size]} is not identical to max pool size #{options[:max_pool_size]}"
+          raise ArgumentError,
+                "Max size #{options[:max_size]} is not identical to max pool size #{options[:max_pool_size]}"
         end
         if options[:wait_timeout] && options[:wait_queue_timeout] && options[:wait_timeout] != options[:wait_queue_timeout]
-          raise ArgumentError, "Wait timeout #{options[:wait_timeout]} is not identical to wait queue timeout #{options[:wait_queue_timeout]}"
+          raise ArgumentError,
+                "Wait timeout #{options[:wait_timeout]} is not identical to wait queue timeout #{options[:wait_queue_timeout]}"
         end
+
         options[:min_size] ||= options[:min_pool_size]
         options.delete(:min_pool_size)
         options[:max_size] ||= options[:max_pool_size]
         options.delete(:max_pool_size)
         if options[:min_size] && options[:max_size] &&
-          (options[:max_size] != 0 && options[:min_size] > options[:max_size])
-        then
+           options[:max_size] != 0 && options[:min_size] > options[:max_size]
           raise ArgumentError, "Cannot have min size #{options[:min_size]} exceed max size #{options[:max_size]}"
         end
-        if options[:wait_queue_timeout]
-          options[:wait_timeout] ||= options[:wait_queue_timeout]
-        end
+
+        options[:wait_timeout] ||= options[:wait_queue_timeout] if options[:wait_queue_timeout]
         options.delete(:wait_queue_timeout)
 
         @server = server
@@ -137,18 +136,25 @@ module Mongo
         # A connection owned by this pool should be either in the
         # available connections array (which is used as a stack)
         # or in the checked out connections set.
-        @available_connections = available_connections = []
+        @available_connections = []
         @checked_out_connections = Set.new
         @pending_connections = Set.new
         @interrupt_connections = []
 
+        # RUBY-3364: count threads currently blocked on size_cv /
+        # max_connecting_cv. When non-zero, a newly-arriving thread must
+        # enter the wait queue even if the gate predicate is currently
+        # satisfied, to prevent barging past existing waiters.
+        @size_waiters = 0
+        @max_connecting_waiters = 0
+
         # Mutex used for synchronizing access to @available_connections and
         # @checked_out_connections. The pool object is thread-safe, thus
         # all methods that retrieve or modify instance variables generally
         # must do so under this lock.
         @lock = Mutex.new
 
-        # Background thread reponsible for maintaining the size of
+        # Background thread responsible for maintaining the size of
         # the pool to at least min_size
         @populator = Populator.new(self, options)
         @populate_semaphore = Semaphore.new
@@ -164,12 +170,13 @@ module Mongo
         @connection_requests = 0
 
         # Condition variable to enforce the second check in check_out: max_connecting.
-        # Thei condition variable should be signaled when the number of pending
+        # This condition variable should be signaled when the number of pending
         # connections decreases.
         @max_connecting_cv = Mongo::ConditionVariable.new(@lock)
         @max_connecting = options.fetch(:max_connecting, DEFAULT_MAX_CONNECTING)
 
-        ObjectSpace.define_finalizer(self, self.class.finalize(@available_connections, @pending_connections, @populator))
+        ObjectSpace.define_finalizer(self,
+                                     self.class.finalize(@available_connections, @pending_connections, @populator))
 
         publish_cmap_event(
           Monitoring::Event::Cmap::PoolCreated.new(@server.address, options, self)
@@ -191,7 +198,7 @@ module Mongo
       #
       # @since 2.9.0
       def max_size
-        @max_size ||= options[:max_size] || [DEFAULT_MAX_SIZE, min_size].max
+        @max_size ||= options[:max_size] || [ DEFAULT_MAX_SIZE, min_size ].max
       end
 
       # Get the minimum size of the connection pool.
@@ -321,12 +328,12 @@ module Mongo
       def summary
         @lock.synchronize do
           state = if closed?
-            'closed'
-          elsif !@ready
-            'paused'
-          else
-            'ready'
-          end
+                    'closed'
+                  elsif !@ready
+                    'paused'
+                  else
+                    'ready'
+                  end
           "#<ConnectionPool size=#{unsynchronized_size} (#{min_size}-#{max_size}) " +
             "used=#{@checked_out_connections.length} avail=#{@available_connections.length} pending=#{@pending_connections.length} #{state}>"
         end
@@ -378,13 +385,12 @@ module Mongo
         )
 
         publish_cmap_event(
-          Monitoring::Event::Cmap::ConnectionCheckedOut.new(@server.address, connection.id, self),
+          Monitoring::Event::Cmap::ConnectionCheckedOut.new(@server.address, connection.id, self)
         )
 
-        if Lint.enabled?
-          unless connection.connected?
-            raise Error::LintError, "Connection pool for #{address} checked out a disconnected connection #{connection.generation}:#{connection.id}"
-          end
+        if Lint.enabled? && !connection.connected?
+          raise Error::LintError,
+                "Connection pool for #{address} checked out a disconnected connection #{connection.generation}:#{connection.id}"
         end
 
         connection
@@ -392,6 +398,23 @@ module Mongo
         check_invariants
       end
 
+      # Returns a pinned connection that is already checked out, if one
+      # exists with the given global id. Returns nil otherwise.
+      #
+      # @param [ Integer ] connection_global_id The global id of the pinned
+      #   connection.
+      #
+      # @return [ Connection | nil ] The pinned connection, or nil.
+      #
+      # @api private
+      def check_out_pinned_connection(connection_global_id)
+        @lock.synchronize do
+          @checked_out_connections.detect do |conn|
+            conn.global_id == connection_global_id && conn.pinned?
+          end
+        end
+      end
+
       # Check a connection back into the pool.
       #
       # The connection must have been previously created by this pool.
@@ -420,14 +443,16 @@ module Mongo
         return if connection.closed? && connection.interrupted?
 
         unless connection.connection_pool == self
-          raise ArgumentError, "Trying to check in a connection which was not checked out by this pool: #{connection} checked out from pool #{connection.connection_pool} (for #{self})"
+          raise ArgumentError,
+                "Trying to check in a connection which was not checked out by this pool: #{connection} checked out from pool #{connection.connection_pool} (for #{self})"
         end
 
         unless @checked_out_connections.include?(connection)
-          raise ArgumentError, "Trying to check in a connection which is not currently checked out by this pool: #{connection} (for #{self})"
+          raise ArgumentError,
+                "Trying to check in a connection which is not currently checked out by this pool: #{connection} (for #{self})"
         end
 
-        # Note: if an event handler raises, resource will not be signaled.
+        # NOTE: if an event handler raises, resource will not be signaled.
         # This means threads waiting for a connection to free up when
         # the pool is at max size may time out.
         # Threads that begin waiting after this method completes (with
@@ -495,7 +520,7 @@ module Mongo
           raise Error::LintError, "Attempting to pause pool for server #{@server.summary} which is known"
         end
 
-        return if !@ready
+        return unless @ready
 
         @ready = false
       end
@@ -551,9 +576,7 @@ module Mongo
           # Generation must be bumped before emitting pool cleared event.
           @generation_manager.bump(service_id: service_id)
 
-          unless options && options[:lazy]
-            close_available_connections(service_id)
-          end
+          close_available_connections(service_id) unless options && options[:lazy]
 
           if options && options[:interrupt_in_use_connections]
             schedule_for_interruption(@checked_out_connections, service_id)
@@ -618,12 +641,12 @@ module Mongo
           Monitoring::Event::Cmap::PoolReady.new(@server.address, options, self)
         )
 
-        if options.fetch(:populator_io, true)
-          if @populator.running?
-            @populate_semaphore.signal
-          else
-            @populator.run!
-          end
+        return unless options.fetch(:populator_io, true)
+
+        if @populator.running?
+          @populate_semaphore.signal
+        else
+          @populator.run!
         end
       end
 
@@ -715,16 +738,35 @@ module Mongo
       def with_connection(connection_global_id: nil, context: nil)
         raise_if_closed!
 
-        connection = check_out(
+        # If a specific connection is requested and it is already checked out
+        # and pinned (e.g. for a transaction or cursor in load-balanced mode),
+        # reuse it directly without going through the check_out/check_in cycle.
+        if connection_global_id
+          connection = @lock.synchronize do
+            @checked_out_connections.detect do |conn|
+              conn.global_id == connection_global_id && conn.pinned?
+            end
+          end
+        end
+
+        connection ||= check_out(
           connection_global_id: connection_global_id,
           context: context
         )
+
         yield(connection)
       rescue Error::SocketError, Error::SocketTimeoutError, Error::ConnectionPerished => e
         maybe_raise_pool_cleared!(connection, e)
       ensure
-        if connection
-          check_in(connection)
+        if connection && !connection.pinned?
+          # Do not check in if the connection is pinned (the session or cursor
+          # owns it and will check it in later when unpinning). Also skip
+          # check-in if the connection was already checked in during the block
+          # (e.g. by Session#unpin after an error on the first operation).
+          checked_out = @lock.synchronize do
+            @checked_out_connections.include?(connection)
+          end
+          check_in(connection) if checked_out
         end
       end
 
@@ -740,13 +782,11 @@ module Mongo
           i = 0
           while i < @available_connections.length
             connection = @available_connections[i]
-            if last_checkin = connection.last_checkin
-              if (Time.now - last_checkin) > max_idle_time
-                connection.disconnect!(reason: :idle)
-                @available_connections.delete_at(i)
-                @populate_semaphore.signal
-                next
-              end
+            if (last_checkin = connection.last_checkin) && ((Time.now - last_checkin) > max_idle_time)
+              connection.disconnect!(reason: :idle)
+              @available_connections.delete_at(i)
+              @populate_semaphore.signal
+              next
             end
             i += 1
           end
@@ -787,7 +827,7 @@ module Mongo
       # @return [ true | false ] Whether this method should be called again
       #   to create more connections.
       # @raise [ Error::AuthError, Error ] The second socket-related error raised if a retry
-      # occured, or the non socket-related error
+      # occurred, or the non socket-related error
       #
       # @api private
       def populate
@@ -801,7 +841,7 @@ module Mongo
           log_warn("Populator failed to connect a connection for #{address}: #{e.class}: #{e}. It will retry.")
         end
 
-        return create_and_add_connection
+        create_and_add_connection
       end
 
       # Finalize the connection pool for garbage collection.
@@ -811,7 +851,7 @@ module Mongo
       # @param [ Populator ] populator The populator.
       #
       # @return [ Proc ] The Finalizer.
-      def self.finalize(available_connections, pending_connections, populator)
+      def self.finalize(available_connections, pending_connections, _populator)
         proc do
           available_connections.each do |connection|
             connection.disconnect!(reason: :pool_closed)
@@ -841,9 +881,7 @@ module Mongo
           conn = @available_connections.detect do |conn|
             conn.global_id == connection_global_id
           end
-          if conn
-            @available_connections.delete(conn)
-          end
+          @available_connections.delete(conn) if conn
           conn
         else
           @available_connections.pop
@@ -851,16 +889,14 @@ module Mongo
       end
 
       def create_connection
-        r, _ = @generation_manager.pipe_fds(service_id: server.description.service_id)
+        r, = @generation_manager.pipe_fds(service_id: server.description.service_id)
         opts = options.merge(
           connection_pool: self,
           pipe: r
           # Do not pass app metadata - this will be retrieved by the connection
           # based on the auth needs.
         )
-        unless @server.load_balancer?
-          opts[:generation] = generation
-        end
+        opts[:generation] = generation unless @server.load_balancer?
         Connection.new(@server, opts)
       end
 
@@ -875,14 +911,14 @@ module Mongo
 
         @lock.synchronize do
           if !closed? && @ready &&
-            (unsynchronized_size + @connection_requests) < min_size &&
-            @pending_connections.length < @max_connecting
-          then
+             (unsynchronized_size + @connection_requests) < min_size &&
+             @pending_connections.length < @max_connecting
             connection = create_connection
             @pending_connections << connection
           else
             return true if remove_interrupted_connections
             return true if remove_stale_connection
+
             return false
           end
         end
@@ -910,11 +946,11 @@ module Mongo
 
       # Removes and disconnects all stale available connections.
       def remove_stale_connection
-        if conn = @available_connections.detect(&method(:connection_stale_unlocked?))
-          conn.disconnect!(reason: :stale)
-          @available_connections.delete(conn)
-          return true
-        end
+        return unless conn = @available_connections.detect { |c| connection_stale_unlocked?(c) }
+
+        conn.disconnect!(reason: :stale)
+        @available_connections.delete(conn)
+        true
       end
 
       # Interrupt connections scheduled for interruption.
@@ -957,7 +993,7 @@ module Mongo
       # @return [ true | false ] Whether the connection is stale.
       def connection_stale_unlocked?(connection)
         connection.generation != generation_unlocked(service_id: connection.service_id) &&
-        !connection.pinned?
+          !connection.pinned?
       end
 
       # Asserts that the pool has not been closed.
@@ -966,9 +1002,9 @@ module Mongo
       #
       # @since 2.9.0
       def raise_if_closed!
-        if closed?
-          raise Error::PoolClosedError.new(@server.address, self)
-        end
+        return unless closed?
+
+        raise Error::PoolClosedError.new(@server.address, self)
       end
 
       # If the connection was interrupted, raise a pool cleared error. If it
@@ -980,31 +1016,36 @@ module Mongo
       # @raise [ Mongo::Error | Mongo::Error::PoolClearedError ] A PoolClearedError
       #   if the connection was interrupted, the original error if not.
       def maybe_raise_pool_cleared!(connection, e)
-        if connection&.interrupted?
-          err = Error::PoolClearedError.new(connection.server.address, connection.server.pool_internal).tap do |err|
-            e.labels.each { |l| err.add_label(l) }
-          end
-          raise err
-        else
-          raise e
+        raise e unless connection&.interrupted?
+
+        err = Error::PoolClearedError.new(connection.server.address, connection.server.pool_internal).tap do |err|
+          e.labels.each { |l| err.add_label(l) }
         end
+        raise err
       end
 
       # Attempts to connect (handshake and auth) the connection. If an error is
       # encountered, closes the connection and raises the error.
       def connect_connection(connection, context = nil)
-        begin
-          connection.connect!(context)
-        rescue Exception
-          connection.disconnect!(reason: :error)
-          raise
+        connection.connect!(context)
+      rescue Exception => e
+        # When a connection encounters an error during creation
+        # (including handshake and authentication), mark the server
+        # as Unknown so the pool is cleared (per CMAP spec).
+        # The unknown! call must happen before disconnect! so that
+        # the ConnectionPoolCleared event is published before the
+        # ConnectionClosed event.
+        # Errors with the SystemOverloadedError label (network errors
+        # during handshake) are excluded per the SDAM spec — those
+        # must not change the server description.
+        if e.is_a?(Mongo::Error) && !e.label?('SystemOverloadedError')
+          @server.unknown!(
+            generation: e.generation,
+            service_id: e.service_id,
+            stop_push_monitor: true
+          )
         end
-      rescue Error::SocketError, Error::SocketTimeoutError => exc
-        @server.unknown!(
-          generation: exc.generation,
-          service_id: exc.service_id,
-          stop_push_monitor: true,
-        )
+        connection.disconnect!(reason: :error)
         raise
       end
 
@@ -1039,15 +1080,13 @@ module Mongo
           loop do
             conn = @available_connections.detect do |conn|
               conn.service_id == service_id &&
-              conn.generation < @generation_manager.generation(service_id: service_id)
-            end
-            if conn
-              @available_connections.delete(conn)
-              conn.disconnect!(reason: :stale, interrupted: true)
-              @populate_semaphore.signal
-            else
-              break
+                conn.generation < @generation_manager.generation(service_id: service_id)
             end
+            break unless conn
+
+            @available_connections.delete(conn)
+            conn.disconnect!(reason: :stale, interrupted: true)
+            @populate_semaphore.signal
           end
         else
           @available_connections.delete_if do |conn|
@@ -1067,7 +1106,7 @@ module Mongo
       def schedule_for_interruption(connections, service_id)
         @interrupt_connections += connections.select do |conn|
           (!server.load_balancer? || conn.service_id == service_id) &&
-          conn.generation < @generation_manager.generation(service_id: service_id)
+            conn.generation < @generation_manager.generation(service_id: service_id)
         end
       end
 
@@ -1087,23 +1126,23 @@ module Mongo
         publish_cmap_event(
           Monitoring::Event::Cmap::ConnectionCheckOutFailed.new(
             @server.address,
-            Monitoring::Event::Cmap::ConnectionCheckOutFailed::TIMEOUT,
-          ),
+            Monitoring::Event::Cmap::ConnectionCheckOutFailed::TIMEOUT
+          )
         )
 
         connection_global_id_msg = if connection_global_id
-          " for connection #{connection_global_id}"
-        else
-          ''
-        end
-
-        msg = "Timed out attempting to check out a connection " +
-          "from pool for #{@server.address}#{connection_global_id_msg} after #{wait_timeout} sec. " +
-          "Connections in pool: #{@available_connections.length} available, " +
-          "#{@checked_out_connections.length} checked out, " +
-          "#{@pending_connections.length} pending, " +
-          "#{@connection_requests} connections requests " +
-          "(max size: #{max_size})"
+                                     " for connection #{connection_global_id}"
+                                   else
+                                     ''
+                                   end
+
+        msg = 'Timed out attempting to check out a connection ' +
+              "from pool for #{@server.address}#{connection_global_id_msg} after #{wait_timeout} sec. " +
+              "Connections in pool: #{@available_connections.length} available, " +
+              "#{@checked_out_connections.length} checked out, " +
+              "#{@pending_connections.length} pending, " +
+              "#{@connection_requests} connections requests " +
+              "(max size: #{max_size})"
         raise Error::ConnectionCheckOutTimeout.new(msg, address: @server.address)
       end
 
@@ -1114,31 +1153,31 @@ module Mongo
       end
 
       def raise_if_pool_closed!
-        if closed?
-          publish_cmap_event(
-            Monitoring::Event::Cmap::ConnectionCheckOutFailed.new(
-              @server.address,
-              Monitoring::Event::Cmap::ConnectionCheckOutFailed::POOL_CLOSED
-            ),
+        return unless closed?
+
+        publish_cmap_event(
+          Monitoring::Event::Cmap::ConnectionCheckOutFailed.new(
+            @server.address,
+            Monitoring::Event::Cmap::ConnectionCheckOutFailed::POOL_CLOSED
           )
-          raise Error::PoolClosedError.new(@server.address, self)
-        end
+        )
+        raise Error::PoolClosedError.new(@server.address, self)
       end
 
       def raise_if_pool_paused!
         raise_unless_locked!
 
-        if !@ready
-          publish_cmap_event(
-            Monitoring::Event::Cmap::ConnectionCheckOutFailed.new(
-              @server.address,
-              # CMAP spec decided to conflate pool paused with all the other
-              # possible non-timeout errors.
-              Monitoring::Event::Cmap::ConnectionCheckOutFailed::CONNECTION_ERROR,
-            ),
+        return if @ready
+
+        publish_cmap_event(
+          Monitoring::Event::Cmap::ConnectionCheckOutFailed.new(
+            @server.address,
+            # CMAP spec decided to conflate pool paused with all the other
+            # possible non-timeout errors.
+            Monitoring::Event::Cmap::ConnectionCheckOutFailed::CONNECTION_ERROR
           )
-          raise Error::PoolPausedError.new(@server.address, self)
-        end
+        )
+        raise Error::PoolPausedError.new(@server.address, self)
       end
 
       def raise_if_pool_paused_locked!
@@ -1155,12 +1194,12 @@ module Mongo
       end
 
       def raise_unless_locked!
-        unless @lock.owned?
-          raise ArgumentError, "the lock must be owned when calling this method"
-        end
+        return if @lock.owned?
+
+        raise ArgumentError, 'the lock must be owned when calling this method'
       end
 
-      def valid_available_connection?(connection, pid, connection_global_id)
+      def valid_available_connection?(connection, pid, _connection_global_id)
         if connection.pid != pid
           log_warn("Detected PID change - Mongo client should have been reconnected (old pid #{connection.pid}, new pid #{pid}")
           connection.disconnect!(reason: :stale)
@@ -1168,7 +1207,7 @@ module Mongo
           return false
         end
 
-        if !connection.pinned?
+        unless connection.pinned?
           # If connection is marked as pinned, it is used by a transaction
           # or a series of cursor operations in a load balanced setup.
           # In this case connection should not be disconnected until
@@ -1184,8 +1223,7 @@ module Mongo
           end
 
           if max_idle_time && connection.last_checkin &&
-            Time.now - connection.last_checkin > max_idle_time
-          then
+             Time.now - connection.last_checkin > max_idle_time
             connection.disconnect!(reason: :idle)
             @populate_semaphore.signal
             return false
@@ -1209,9 +1247,7 @@ module Mongo
       #   and remains so for longer than the wait timeout.
       def get_connection(pid, connection_global_id)
         if connection = next_available_connection(connection_global_id)
-          unless valid_available_connection?(connection, pid, connection_global_id)
-            return nil
-          end
+          return nil unless valid_available_connection?(connection, pid, connection_global_id)
 
           # We've got a connection, so we decrement the number of connection
           # requests.
@@ -1222,13 +1258,11 @@ module Mongo
           # If the connection is connected, it's not considered a
           # "pending connection". The pending_connections list represents
           # the set of connections that are awaiting connection.
-          unless connection.connected?
-            @pending_connections << connection
-          end
-          return connection
+          @pending_connections << connection unless connection.connected?
+          connection
         elsif connection_global_id && @server.load_balancer?
           # A particular connection is requested, but it is not available.
-          # If it is nether available not checked out, we should stop here.
+          # If it is neither available nor checked out, we should stop here.
           @checked_out_connections.detect do |conn|
             conn.global_id == connection_global_id
           end.tap do |conn|
@@ -1237,7 +1271,7 @@ module Mongo
                 Monitoring::Event::Cmap::ConnectionCheckOutFailed.new(
                   @server.address,
                   Monitoring::Event::Cmap::ConnectionCheckOutFailed::CONNECTION_ERROR
-                ),
+                )
               )
               # We're going to raise, so we need to decrement the number of
               # connection requests.
@@ -1253,7 +1287,7 @@ module Mongo
           connection = create_connection
           @connection_requests -= 1
           @pending_connections << connection
-          return connection
+          connection
         end
       end
 
@@ -1269,18 +1303,32 @@ module Mongo
       # @raise [ Error::PoolClosedError ] If the pool has been closed.
       # @raise [ Timeout::Error ] If the connection pool is at maximum size
       #   and remains so for longer than the wait timeout.
-      def retrieve_and_connect_connection(connection_global_id, context =  nil)
+      def retrieve_and_connect_connection(connection_global_id, context = nil)
         deadline = Utils.monotonic_time + wait_timeout(context)
         connection = nil
 
         @lock.synchronize do
-          # The first gate to checking out a connection. Make sure the number of
-          # unavailable connections is less than the max pool size.
-          until max_size == 0 || unavailable_connections < max_size
+          # RUBY-3364: if any thread is already waiting for a size slot,
+          # join the queue even when the gate predicate is currently
+          # satisfied. Without this, re-entering threads (those that just
+          # checked a connection back in) barge past existing waiters and
+          # the 195 blocked threads in a 200:5 scenario never wake.
+          # Skip the gate for unlimited pools (max_size == 0) where there
+          # is no size constraint to wait on.
+          must_wait = max_size != 0 && @size_waiters > 0
+          until (max_size == 0 || unavailable_connections < max_size) && !must_wait
             wait = deadline - Utils.monotonic_time
             raise_check_out_timeout!(connection_global_id) if wait <= 0
-            @size_cv.wait(wait)
+            @size_waiters += 1
+            begin
+              @size_cv.wait(wait)
+            ensure
+              @size_waiters -= 1
+            end
             raise_if_not_ready!
+            # After one wait cycle we have served our "queue tax" and
+            # compete for the slot on the next predicate check.
+            must_wait = false
           end
           @connection_requests += 1
           connection = wait_for_connection(connection_global_id, deadline)
@@ -1290,15 +1338,28 @@ module Mongo
 
         @lock.synchronize do
           @checked_out_connections << connection
-          if @pending_connections.include?(connection)
-            @pending_connections.delete(connection)
-          end
+          @pending_connections.delete(connection) if @pending_connections.include?(connection)
           @max_connecting_cv.signal
-          # no need to signal size_cv here since the number of unavailable
-          # connections is unchanged.
+          # RUBY-3364: hand off the baton. A waiter that arrived during
+          # our wake-up window (seeing our stale @size_waiters > 0) may be
+          # parked on @size_cv with capacity already available. The
+          # regular check-in path is the only other place that signals
+          # @size_cv, so we wake the next waiter only when the predicate
+          # is actually satisfied for them. Signaling unconditionally
+          # would re-queue a waiter at the back of the FIFO and break
+          # ordering.
+          if @size_waiters > 0 && (max_size == 0 || unavailable_connections < max_size)
+            @size_cv.signal
+          end
         end
 
         connection
+      rescue Error::ConnectionCheckOutTimeout
+        # Per the CSOT spec, if a connection checkout fails because the CSOT
+        # deadline expired (rather than a configured waitQueueTimeout), the
+        # error must be a CSOT TimeoutError so that callers can distinguish it.
+        context&.check_timeout!
+        raise
       end
 
       # Waits for a connection to become available, or raises is no connection
@@ -1311,9 +1372,12 @@ module Mongo
       def wait_for_connection(connection_global_id, deadline)
         connection = nil
         while connection.nil?
+          # RUBY-3364: as above, yield to any thread already queued for
+          # a max_connecting slot before competing ourselves.
+          must_wait = @max_connecting_waiters > 0
           # The second gate to checking out a connection. Make sure 1) there
           # exists an available connection and 2) we are under max_connecting.
-          until @available_connections.any? || @pending_connections.length < @max_connecting
+          until (@available_connections.any? || @pending_connections.length < @max_connecting) && !must_wait
             wait = deadline - Utils.monotonic_time
             if wait <= 0
               # We are going to raise a timeout error, so the connection
@@ -1322,21 +1386,35 @@ module Mongo
               decrement_connection_requests_and_signal
               raise_check_out_timeout!(connection_global_id)
             end
-            @max_connecting_cv.wait(wait)
+            @max_connecting_waiters += 1
+            begin
+              @max_connecting_cv.wait(wait)
+            ensure
+              @max_connecting_waiters -= 1
+            end
             # We do not need to decrement the connection_requests counter
             # or signal here because the pool is not ready yet.
             raise_if_not_ready!
+            must_wait = false
           end
 
           connection = get_connection(Process.pid, connection_global_id)
           wait = deadline - Utils.monotonic_time
-          if connection.nil? && wait <= 0
-            # connection is nil here, it means that get_connection method
-            # did not create a new connection; therefore, it did not decrease
-            # the connection_requests counter. We need to do it here.
-            decrement_connection_requests_and_signal
-            raise_check_out_timeout!(connection_global_id)
-          end
+          next unless connection.nil? && wait <= 0
+
+          # connection is nil here, it means that get_connection method
+          # did not create a new connection; therefore, it did not decrease
+          # the connection_requests counter. We need to do it here.
+          decrement_connection_requests_and_signal
+          raise_check_out_timeout!(connection_global_id)
+        end
+
+        # RUBY-3364: hand off the baton for max_connecting_cv. Signal
+        # only if the gate predicate is satisfied for the next waiter, to
+        # avoid re-queuing a waiter at the back of the FIFO.
+        if @max_connecting_waiters > 0 &&
+           (@available_connections.any? || @pending_connections.length < @max_connecting)
+          @max_connecting_cv.signal
         end
 
         connection
@@ -1351,9 +1429,7 @@ module Mongo
       rescue Exception
         # Handshake or authentication failed
         @lock.synchronize do
-          if @pending_connections.include?(connection)
-            @pending_connections.delete(connection)
-          end
+          @pending_connections.delete(connection) if @pending_connections.include?(connection)
           @max_connecting_cv.signal
           @size_cv.signal
         end
@@ -1362,12 +1438,11 @@ module Mongo
           Monitoring::Event::Cmap::ConnectionCheckOutFailed.new(
             @server.address,
             Monitoring::Event::Cmap::ConnectionCheckOutFailed::CONNECTION_ERROR
-          ),
+          )
         )
         raise
       end
 
-
       # Decrement connection requests counter and signal the condition
       # variables that the number of unavailable connections has decreased.
       def decrement_connection_requests_and_signal