异步和同步 API

在此页面上

Overview
配置异步运行时
Tokio 运行时示例
配置同步 API
同步代码示例
同时使用异步和同步 API
更多信息
API 文档

Overview

在本指南中，您可以了解 Rust 驱动程序的异步和同步API。本指南介绍了如何启用可用的 API 并构建代码以使用每个 API。

Rust驾驶员支持tokio异步运行时 crate，这是默认运行时。

该驱动程序还包括一个同步 API，适用于需要阻塞或不需要并行的使用案例。您可以通过将功能标志添加到Cargo.toml文件中的mongodb依赖项来选择同步 API。

本指南包括以下部分：

配置异步运行时展示了如何配置应用程序以使用tokio异步运行时
配置同步API展示了如何配置应用程序以使用sync和tokio-sync同步运行时
同时使用异步和同步 API展示了如何在应用程序中同时启用异步和同步运行时 API
附加信息提供了本指南中提到的类型和方法的资源和 API 文档链接

配置异步运行时

驾驶员默认使用tokio运行时，因此您可以使用此运行时，而无需在项目的Cargo.toml文件中指定任何功能标志。有关安装驾驶员和配置Cargo.toml文件的更多信息，请参阅快速入门的下载和安装步骤。

重要

从Rust驾驶员v 3.0开始， tokio运行时是驾驶员支持的唯一异步运行时包。上一个版本的驾驶员还支持async-std运行时包。

如果应用程序使用async-std运行时，则可以在同一应用程序中启动tokio运行时，方法是创建Runtime结构体实例并使用Runtime::spawn()方法封装驾驶员操作。确保使用相同的Runtime实例来实例化Client并在该Client实例上调用驾驶员方法。

Runtimespawn()有关示例化和调用方法的示例，请参阅 tokio 文档。

Tokio 运行时示例

以下代码使用tokio包中的task模块为多个数据操作创建单独的并发任务：

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).await
    });
}

配置同步 API

该驾驶员还提供阻塞、同步API。要使用tokio同步API，请将"sync"功能标志添加到mongodb依赖项中，如以下示例所示：

[dependencies.mongodb]
version = "3.2.3"
features = ["sync"]

同步代码示例

使用同步 API 时，请使用mongodb::sync模块中的类型来执行操作。以下代码使用sync模块通过同步 API 将数据插入到集合中。当insert_one方法在for循环内运行时，驱动程序会等待每个请求完成后再继续。

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);
    }
}

同时使用异步和同步 API

您可以在同一应用程序中使用异步和同步 API。示例，要启用两个tokio运行时，可以将tokio依赖项添加到依赖项列表中，并将"sync"标志添加到mongodb依赖项中：

[dependencies]
futures = "0.3.28"
tokio = {version = "1.32.0", features = ["full"]}
[dependencies.mongodb]
version = "3.2.3"
features = ["sync"]