DOCSP-30506 Async and Sync Runtimes (#54)

Co-authored-by: Rea Rustagi <[email protected]>

Author: pierwill

source/fundamentals.txt

@@ -21,6 +21,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/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

@@ -14,6 +14,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
+    });
+}