RUBY-3284 Enable max_connecting client option (#2739)

* RUBY-3284 Enable max_connecting client option

* Add validation and error

* Add test for uri option

* More tests

* Docu; bump the version

* Fix connection_requests counter handling

* Fix code review remarks

* Increase timeout

* Update documentation

* Housekeeping

* Update release-notes.txt

* Fix code review remarks

* Revert some changes in spec tests

* Skip flaky jruby test

* Use select (we still support 2.5)

---------

Co-authored-by: Alex Bevilacqua <[email protected]>

Author: comandeo-mongo

source/reference/create-client.txt

@@ -575,6 +575,11 @@ Ruby Options
      - ``Object``
      - ``Logger``
 
+   * - ``:max_connecting``
+     - The maximum number of connections that the connection pool will try to establish in parallel.
+     - ``Integer``
+     - 2
+
    * - ``:max_idle_time``
      - The maximum time, in seconds, that a connection can be idle before it
        is closed by the connection pool.
@@ -1018,6 +1023,9 @@ URI options are explained in detail in the :manual:`Connection URI reference
    * - localThresholdMS=Integer
      - ``:local_threshold => Float``
 
+   * - maxConnecting=Integer
+     - ``:max_connecting => Integer``
+
    * - maxIdleTimeMS=Integer
      - ``:max_idle_time => Float``
 
@@ -1551,6 +1559,14 @@ maximum size, the thread waits for a connection to be returned to the pool by
 another thread. If ``max_pool_size`` is set to zero, there is no limit for the
 maximum number of connections in the pool.
 
+Each pool has a limit on the number of connections that can be concurrently
+connecting to a server. This limit is called ``max_connecting`` and defaults to
+2. If the number of connections that are currently connecting to a server
+reaches this limit, the pool will wait for a connection attempt to succeed or
+fail before attempting to create a new connection. If your application
+has a large number of threads, you may want to increase ``max_connecting`` to avoid
+having threads wait for a connection to be established.
+
 The number of seconds the thread will wait for a connection to become available
 is configurable. This setting, called ``wait_queue_timeout``, is defined in
 seconds. If this timeout is reached, a ``Timeout::Error`` is raised. The
@@ -1595,6 +1611,14 @@ process, increase ``max_pool_size``:
 
     client = Mongo::Client.new(["localhost:27017"], max_pool_size: 200)
 
+To support extremely high numbers of threads that share the same client
+within one process, increase ``max_connecting``:
+
+.. code-block:: ruby
+
+    client = Mongo::Client.new(["localhost:27017"], max_pool_size: 200, max_connecting: 10)
+
+
 Any number of threads are allowed to wait for connections to become available,
 and they can wait the default (1 second) or the ``wait_queue_timeout`` setting:
 
@@ -1627,7 +1651,7 @@ such as Unicorn, Puma or Passenger, or when the application otherwise forks,
 each process should generally each have their own ``Mongo::Client`` instances.
 This is because:
 
-1. The background threads remain in the parent process and are not transfered
+1. The background threads remain in the parent process and are not transferred
    to the child process.
 2. File descriptors like network sockets are shared between parent and
    child processes.

source/release-notes.txt

@@ -28,6 +28,12 @@ now supports Ruby 3.2. Ruby 2.5 and 2.6 are now deprecated.
 
 This release includes the following new features:
 
+- The driver now limits the number of connections established by a connection
+  pool simultaneously. By default the limit is 2. The limit can be configured
+  with the ``:max_connecting`` option of the ``Mongo::Client`` constructor.
+  The default should be sufficient for most applications. However, if your
+  application is using a large number of threads, you may need to increase
+  the limit.
 - Added support for automatic AWS credentials retrieval and authentication
   with temporary credentials when AWS KMS is used for client side encryption.
 - Added support for automatic GCP credentials retrieval when Google Cloud Key