Merge remote-tracking branch 'upstream/master' into v2.7

Author: rustagir

source/fundamentals.txt

@@ -22,6 +22,7 @@ Fundamentals
    /fundamentals/tracing-logging
    /fundamentals/run-command
    /fundamentals/performance
+   /fundamentals/runtimes
 
 ..
    Connect to MongoDB Atlas from AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>

source/fundamentals/run-command.txt

@@ -21,10 +21,10 @@ statistics, initializing a replica set, or running an aggregation pipeline.
 This guide includes the following sections:
 
 - :ref:`Execute a Command <rust-execute-command>` describes the syntax
-  and behavior of the ``run_command()`` method
+  and behavior of the ``run_command()`` and ``run_cursor_command()`` methods
 
 - :ref:`Response <rust-command-response>` describes the information
-  that the ``run_command()`` method returns
+  that the command execution methods return
 
 - :ref:`Command Example <rust-command-example>` provides a command
   example and describes the output for the command
@@ -51,8 +51,15 @@ Execute a Command
 -----------------
 
 To run a database command, you must specify the command and any relevant
-parameters in a command document, then pass the command document to the
-``run_command()`` method.
+parameters in a command document, then pass the command document to a
+command execution method. The {+driver-short+} provides the following methods
+to run database commands:
+
+- ``run_command()``, which returns the command response as a
+  ``Document`` type. You can use this method with any database command.
+- ``run_cursor_command()``, which returns the command response as an iterable
+  ``Cursor`` type. You can use this method only if your database command
+  returns multiple result documents.
 
 The following code shows how you can use the ``run_command()``
 method to run the ``hello`` command, which returns information about
@@ -62,28 +69,43 @@ the current member's role in the replica set, on a database:
 
    let result = my_db.run_command(doc! { "hello": 1 }, None).await?;
 
+The ``checkMetadataConsistency`` command returns multiple result
+documents. You can use the ``run_cursor_command()`` method to run
+this command and collect the results, as shown in the following code:
+
+.. code-block:: rust
+
+   let cursor = my_db
+       .run_cursor_command(doc! { "checkMetadataConsistency": 1 }, None)
+       .await?;
+
 To find a link to a full list of database commands and corresponding
 parameters, see the :ref:`Additional Information section
 <rust-addtl-info-runcommand>`.
 
 .. note:: Read Preference
 
-   The ``run_command()`` method does not obey the read preference you
-   might have set on your ``Database`` object elsewhere in your code. By
-   default, it uses the ``primary`` read preference.
+   The ``run_command()`` and ``run_cursor_command()`` methods do not
+   obey the read preference you might have set on your ``Database``
+   object elsewhere in your code. By default, they use the ``primary``
+   read preference.
 
    You can set a read preference for command execution by
-   passing an options object. The following code shows how to specify a
-   read preference in a ``SelectionCriteria`` instance and pass it as an
-   option to the ``run_command()`` method:
+   passing an options object to either method. The following code shows
+   how to specify a read preference in a ``SelectionCriteria`` instance
+   and pass it as an option to the ``run_command()`` method:
 
    .. code-block:: rust
 
-      let command_options: SelectionCriteria = SelectionCriteria::ReadPreference(
+      let command_options = SelectionCriteria::ReadPreference(
           ReadPreference::Primary
       );
       let result = my_db.run_command(command_doc, command_options).await?;
 
+   The ``run_cursor_command()`` method takes a
+   ``RunCursorCommandOptions`` instance as a parameter. You can set the
+   ``selection_criteria`` field of this struct to select a read preference.
+
    For more information on read preference options, see :manual:`Read
    Preference </core/read-preference/>` in the Server manual.
 
@@ -92,11 +114,14 @@ parameters, see the :ref:`Additional Information section
 Response
 --------
 
-The ``run_command()`` method returns a ``Document`` instance that contains
-the response from the database after the command runs. Each
-database command performs a different function, so the response content
-can vary across commands. However, every response contains a document
-with the following fields:
+The ``run_command()`` method returns a ``Document`` object that contains
+the response from the database after the command has been executed. The
+``run_cursor_command()`` returns a ``Cursor`` that references multiple
+result documents.
+
+Each database command performs a different function, so the response
+content can vary depending on the command executed. However, every
+response contains a document with the following fields:
 
 .. list-table::
    :header-rows: 1
@@ -214,5 +239,7 @@ API Documentation
 ~~~~~~~~~~~~~~~~~
 
 - `run_command() <{+api+}/struct.Database.html#method.run_command>`__
+- `run_cursor_command() <{+api+}/struct.Database.html#method.run_cursor_command>`__
 - `SelectionCriteria <{+api+}/options/enum.SelectionCriteria.html>`__
+- `RunCursorCommandOptions <{+api+}/options/struct.RunCursorCommandOptions.html>`__
 - `ReadPreference <{+api+}/options/enum.ReadPreference.html>`__

source/fundamentals/runtimes.txt

@@ -0,0 +1,148 @@
+.. _rust-runtimes:
+
+=================================
+Asynchronous and Synchronous APIs
+=================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn about the {+driver-short+}'s :ref:`asynchronous <rust-runtimes-configure-async>`
+and :ref:`synchronous <rust-runtimes-configure-sync>` APIs.
+This guide explains how to enable the available APIs and structure your code to use each.
+
+The {+driver-short+} supports ``tokio`` and ``async-std``, two popular asynchronous runtime crates.
+By default, the driver uses the ``tokio`` asynchronous runtime, but you can select a specific runtime
+by adding feature flags to the ``mongodb`` dependency in your ``Cargo.toml`` file.
+
+The driver also includes a synchronous API for use cases that require blocking, or when parallelism is not necessary.
+You can select the synchronous API by adding feature flags to the ``mongodb`` dependency in your ``Cargo.toml`` file.
+
+.. _rust-runtimes-configure-async:
+
+Configure the Asynchronous Runtime
+----------------------------------
+
+The driver uses the ``tokio`` runtime by default.
+You can explicitly choose a runtime by adding the ``"tokio-runtime"`` or ``"async-std-runtime"``
+feature flags to the ``mongodb`` dependency.
+
+Select from the following tabs to see how to add feature flags for each corresponding crate:
+
+.. tabs::
+
+   .. tab:: tokio
+      :tabid: asynchronous-api-tokio
+
+      .. code-block:: toml
+
+         [dependencies.mongodb]
+         version = "{+version+}"
+         features = ["tokio-runtime"]
+
+   .. tab:: async-std
+      :tabid: asynchronous-api-async-std
+
+      .. code-block:: toml
+
+         [dependencies.mongodb]
+         version = "{+version+}"
+         default-features = false
+         features = ["async-std"]
+
+For more information on installing the driver and adding feature flags,
+see the :ref:`rust-quick-start-download-and-install` step of the Quick Start.
+
+Tokio Runtime Example
+~~~~~~~~~~~~~~~~~~~~~
+
+The following code uses the ``task`` module from the ``tokio`` crate
+to create separate, concurrent tasks for multiple data operations:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/runtimes-tokio.rs
+   :language: rust
+   :dedent:
+
+.. _rust-runtimes-configure-sync:
+
+Configure the Synchronous API
+-----------------------------
+
+The driver also provides a blocking, synchronous API.
+To use the synchronous API, add the either the ``"sync"`` or ``"tokio-sync"`` feature flag
+to the ``mongodb`` dependency.
+
+Select from the following tabs to see how to add feature flags for each corresponding crate:
+
+.. tabs::
+
+   .. tab:: sync
+      :tabid: synchronous-api
+
+      .. code-block:: toml
+
+         [dependencies.mongodb]
+         version = "{+version+}"
+         default-features = false
+         features = ["sync"]
+
+   .. tab:: tokio-sync
+      :tabid: synchronous-api-tokio
+
+      .. code-block:: toml
+
+         [dependencies.mongodb]
+         version = "{+version+}"
+         default-features = false
+         features = ["tokio-sync"]
+
+Synchronous Code Example
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When using the synchronous API, use types from the ``mongodb::sync`` module to perform operations.
+The following code uses the ``sync`` module to insert data into a collection using the synchronous API.
+When the ``insert_one`` method runs inside the ``for`` loop, the driver waits for each request to complete before continuing.
+
+.. literalinclude:: /includes/fundamentals/code-snippets/runtimes-sync.rs
+   :language: rust
+   :dedent:
+
+Use Both Asynchronous and Synchronous APIs
+------------------------------------------
+
+You can use both asynchronous and synchronous APIs in the same application.
+For example, to enable both ``tokio`` runtimes, you can add the ``tokio`` dependency to your dependencies list, and add the
+``"tokio-sync"`` flag to the ``mongodb`` dependency:
+
+.. code-block:: toml
+
+   [dependencies]
+   futures = "0.3.28"
+   tokio = {version = "1.32.0", features = ["full"]}
+
+   [dependencies.mongodb]
+   version = "{+version+}"
+   features = ["tokio-sync"]
+
+Additional Information
+----------------------
+
+For more information about the concepts in this guide, see the following pages:
+
+- :ref:`Performance Considerations <rust-performance>`
+- `Asynchronous Programming in Rust <https://rust-lang.github.io/async-book/>`__
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the methods and types discussed in this
+guide, see the following API Documentation:
+
+- `Client <{+api+}/struct.Client.html>`__
+- `sync <{+api+}/sync/index.html>`__

source/includes/fundamentals-sections.rst

@@ -15,6 +15,7 @@ Fundamentals section:
 - :ref:`Record Driver Events <rust-tracing-logging>`
 - :ref:`Run A Database Command <rust-run-command>`
 - :ref:`Optimize Driver Performance <rust-performance>`
+- :ref:`Configure Asynchronous and Synchronous Runtimes <rust-runtimes>`
 
 ..
   - :atlas:`Connect to MongoDB Atlas from AWS Lambda </manage-connections-aws-lambda/>`

source/includes/fundamentals/code-snippets/runtimes-sync.rs

@@ -0,0 +1,17 @@
+use mongodb::sync::Client;
+
+fn main() {
+    let client = Client::with_uri_str("<connection string>")?;
+    let some_data = doc! { "title": "1984", "author": "George Orwell" };
+
+    for i in 0..5 {
+        let client_ref = client.clone();
+        let somedata_ref = some_data.clone();
+
+        let collection = client_ref
+            .database("items")
+            .collection::<Document>(&format!("coll{}", i));
+
+        collection.insert_one(somedata_ref, None);
+    }
+}

source/includes/fundamentals/code-snippets/runtimes-tokio.rs

@@ -0,0 +1,15 @@
+let client = Client::with_uri_str("<connection string>").await?;
+let some_data = doc! { "title": "1984", "author": "George Orwell" };
+
+for i in 0..5 {
+    let client_ref = client.clone();
+    let somedata_ref = some_data.clone();
+
+    task::spawn(async move {
+        let collection = client_ref
+            .database("items")
+            .collection::<Document>(&format!("coll{}", i));
+
+        collection.insert_one(somedata_ref, None).await
+    });
+}