DOCSP-28559: recommend reusing Client (#246)

* DOCSP-28559: recommend reusing Client

* add Faq question

* update

* JS PR fixes 1

Author: rustagir

source/faq.txt

@@ -19,7 +19,85 @@ This page contains frequently asked questions and their corresponding answers.
    If you can't find an answer to your problem on this page,
    see the :ref:`golang-issues-and-help` page for next steps and more
    resources.
+
+.. _golang-faq-connection-pool:
+
+How Does Connection Pooling Work in the {+driver-short+}?
+---------------------------------------------------------
+
+Every ``Client`` instance has a built-in connection pool for each server
+in your MongoDB topology. Connection pools open sockets on demand to support
+concurrent MongoDB operations, or `goroutines
+<https://www.golang-book.com/books/intro/10>`__, in your application.
+
+The maximum size of each connection pool is set by the ``maxPoolSize`` option, which
+defaults to ``100``. If the number of in-use connections to a server reaches
+the value of ``maxPoolSize``, the next request to that server will wait
+until a connection becomes available.
+
+The ``Client`` instance opens two additional sockets per server in your
+MongoDB topology for monitoring the server's state.
+
+For example, a client connected to a 3-node replica set opens 6
+monitoring sockets. It also opens as many sockets as needed to support
+an application's concurrent operations on each server, up to
+the value of ``maxPoolSize``. If ``maxPoolSize`` is ``100`` and the
+application only uses the primary (the default), then only the primary
+connection pool grows and there can be at most ``106`` total connections. If the
+application uses a :ref:`read preference <golang-read-pref>` to query the
+secondary nodes, their pools also grow and there can be ``306`` total connections.
+
+Additionally, connection pools are rate-limited such that each connection pool
+can only create, at maximum, the value of ``maxConnecting`` connections
+in parallel at any time. Any additional goroutine stops waiting in the
+following cases:
+
+- One of the existing goroutines finishes creating a connection, or
+  an existing connection is checked back into the pool.
+- The driver's ability to reuse existing connections improves due to
+  rate-limits on connection creation.
+
+You can set the minimum number of concurrent connections to
+each server with the ``minPoolSize`` option, which defaults to ``0``. The connection pool
+will be initialized with this number of sockets. If sockets are closed
+due to any network errors, causing the total number of sockets (both in
+use and idle) to drop below the minimum, more sockets are opened until
+the minimum is reached.
+
+You can set the maximum number of milliseconds that a connection can
+remain idle in the pool before being removed and replaced with
+the ``maxIdleTimeMS`` option, which defaults to ``None`` (no limit).
+
+The following default configuration for a ``Client`` works for most applications:
+
+.. code-block:: go
 
+   client := mongo.Connect("<connection string>")
+
+Create a client once for each process, and reuse it for all
+operations. It is a common mistake to create a new client for each
+request, which is very inefficient.
+
+To support high numbers of concurrent MongoDB operations
+within one process, you can increase ``maxPoolSize``. Once the pool
+reaches its maximum size, additional operations wait for sockets
+to become available.
+
+The driver does not limit the number of operations that
+can wait for sockets to become available and it is the application's
+responsibility to limit the size of its pool to bound queuing
+during a load spike. Threads can wait for any length of time
+unless you define the ``waitQueueTimeoutMS`` option.
+
+An operation that waits more than the length of time defined by
+``waitQueueTimeoutMS`` for a socket raises a connection error. Use this
+option if it is more important to bound the duration of operations
+during a load spike than it is to complete every operation.
+
+When ``Client.Disconnect()`` is called by any goroutine, the driver
+closes all idle sockets and closes all sockets that are in
+use as they are returned to the pool.
+
 How Can I Fix the "WriteNull can only write while positioned on a Element or Value but is positioned on a TopLevel" Error?
 --------------------------------------------------------------------------------------------------------------------------
 

source/fundamentals/connection.txt

@@ -60,6 +60,15 @@ Connection Example
 To connect to MongoDB, you need to create a client. A client manages
 your connections and runs database commands.
 
+.. tip:: Reuse Your Client
+   
+   We recommend that you reuse your client across sessions and operations.
+   You can use the same ``Client`` instance to perform multiple tasks, instead of
+   creating a new one each time. The ``Client`` type is safe for
+   concurrent use by multiple `goroutines
+   <https://www.golang-book.com/books/intro/10>`__. To learn more about
+   how connection pools work in the driver, see the :ref:`FAQ page <golang-faq-connection-pool>`.
+
 You can create a client that uses your connection string and other
 client options by passing a ``ClientOptions`` object to the ``Connect()``
 method.

source/fundamentals/crud/write-read-pref.txt

@@ -178,6 +178,8 @@ with this option.
    database := client.Database("myDB")
    coll := database.Collection("myCollection", opts)
 
+.. _golang-read-pref:
+
 Read Preference
 ---------------
 

source/fundamentals/transactions.txt

@@ -28,11 +28,13 @@ grouping of related read or write operations that you intend to run
 sequentially. Sessions enable :manual:`causal consistency </core/read-isolation-consistency-recency/#causal-consistency>`
 for a group of operations or allow you to execute operations in an :website:`ACID
 transaction </basics/acid-transactions>`. MongoDB guarantees that the data
-involved in your transaction operations remains , even if the operations
+involved in your transaction operations remains consistent, even if the operations
 encounter unexpected errors.
 
 With the {+driver-short+}, you can create a new session from a
-``Client`` instance as a ``Session`` type.
+``Client`` instance as a ``Session`` type. We recommend that you reuse
+your client for multiple sessions and transactions instead of
+instantiating a new client each time.
 
 .. warning::