FoundationDB Rust客户端API

这是一个围绕FoundationDB (Fdb) C API的包装库。它通过Fdb未来C实现实现了基于future的接口。

先决条件

• Rust 1.70.0或更高版本，
• 已安装FoundationDB客户端。

平台支持

对不同平台（“目标”）的支持分为三个等级，每个等级都有不同的保证。有关每个等级目标政策的更多信息，请参阅目标等级政策。

有关每个等级目标政策的更多信息，请参阅

目标等级政策

一级

等级 1 目标可以被认为是“保证工作”。这意味着

• 我们正在积极使用绑定测试器检查正确性，
• 我们在每个拉取请求上运行经典Rust测试，
• 您可以在该平台上使用该包。

二级

等级 2 目标可以被认为是“保证构建”。这意味着

• 我们在每个拉取请求上运行经典Rust测试，
• 您可以在该平台上使用该包。

但我们没有检查正确性。

三级

等级 3 目标是我们希望成为二级的目标平台。您可能能够编译，但没有设置CI。

入门

安装FoundationDB

您首先需要安装FoundationDB。您可以按照官方文档操作

• Linux入门指南
• 在macOS上入门

在 foundationdb-rs 上添加依赖项

cargo add foundationdb -F embedded-fdb-include
cargo add futures

这个Rust包不依赖于任何异步运行时。

公开的功能

使用此包的Hello, World

我们将使用Tokio运行时进行此示例

use futures::prelude::*;

#[tokio::main]
async fn main() {
    // Safe because drop is called before the program exits
    let network = unsafe { foundationdb::boot() };

    // Have fun with the FDB API
    hello_world().await.expect("could not run the hello world");

    // shutdown the client
    drop(network);
}

async fn hello_world() -> foundationdb::FdbResult<()> {
    let db = foundationdb::Database::default()?;

    // write a value in a retryable closure
    match db
        .run(|trx, _maybe_committed| async move {
            trx.set(b"hello", b"world");
            Ok(())
        })
        .await
    {
        Ok(_) => println!("transaction committed"),
        Err(_) => eprintln!("cannot commit transaction"),
    };

    // read a value
    match db
        .run(|trx, _maybe_committed| async move { Ok(trx.get(b"hello", false).await.unwrap()) })
        .await
    {
        Ok(slice) => assert_eq!(b"world", slice.unwrap().as_ref()),
        Err(_) => eprintln!("cannot commit transaction"),
    }

    Ok(())
}

其他注意事项

类调度教程

官方FoundationDB教程称为类调度。Rust版本可在此处找到。

blob教程

官方FoundationDB文档还提供了另一个主题，在设计配方中进一步讨论。Rust实现可在此处找到。

另一个示例，探讨了如何使用子空间将元数据附加到我们的blob。

必读文档

• 开发者指南
• 数据建模指南

初始化

由于C API的限制，Client及其关联的网络只能在进程的生命周期中初始化和运行一次。通常，foundationdb::boot函数足以初始化Client。有关Fdb Client的更多配置选项，请参阅foundationdb::api。

从0.4迁移到0.5

由于仅使用安全代码时可能存在未定义的行为（问题#170，#181，拉动请求#179，#182），因此修改了foundationdb API的初始化。

之前您必须编写foundationdb::boot().expect("failed to initialize Fdb");，现在这可以转换为

// Safe because drop is called before the program exits
let network = unsafe { foundationdb::boot() };

// do stuff

// cleanly shutdown the client
drop(network);

API稳定性

警告 在此库的1.0版本发布之前，API可能处于不断变化之中。