Tarantool Rust SDK

Tarantool Rust SDK 为 Rust 应用程序与 Tarantool 交互提供了一个库。本文档描述了 Rust 的 Tarantool API 绑定，包括以下 API：

• Box：空间、索引、序列
• Fibers：纤维属性、条件变量、互斥锁、异步运行时
• CoIO
• 事务
• 模式管理
• 协议实现 (net.box)：CRUD、存储过程调用、触发器
• 元组工具
• 日志（见 https://docs.rs/log/）
• 错误处理

链接

• 包页面
• API 文档
• 仓库

另请参阅

• https://tarantool.io
• https://github.com/tarantool/tarantool

入门

以下说明将帮助您在本地机器上获取项目的副本并运行。有关部署，请查看文件末尾的部署说明。

先决条件

• Tarantool 2.10+

macOS 中的链接问题

在 macOS 上，您可能会遇到如下链接错误：ld: symbol(s) not found for architecture x86_64。为了解决这个问题，请将以下行添加到您的 $CARGO_HOME/config.toml（默认为 ~/.cargo/config.toml）中。

[target.x86_64-apple-darwin]
rustflags = [
    "-C", "link-arg=-undefined",  "-C", "link-arg=dynamic_lookup"
]

用法

将以下行添加到您的项目 Cargo.toml 中

[dependencies]
tarantool = "4.0"

[lib]
crate-type = ["cdylib"]

有关示例用法，请参阅 https://github.com/picodata/brod。

特性

• net_box - 启用协议实现（默认启用）
• schema - 启用模式操作工具（目前为 WIP）

存储过程

Tarantool 可以通过多种方式调用 Rust 代码。它可以使用插件、Lua 到 Rust FFI 代码生成器或存储过程。在此文件中，我们仅涵盖第三种选项，即 Rust 存储过程。尽管 Tarantool 总是将 Rust 例程视为“C 函数”，但我们继续使用“存储过程”一词作为约定和历史上的原因。

本教程包含以下简单步骤

1. examples/easy - 打印 "hello world";
2. examples/harder - 解码传入的参数值;
3. examples/hardest - 使用此库进行数据库管理系统（DBMS）插入;
4. examples/read - 使用此库进行DBMS选择;
5. examples/write - 使用此库进行DBMS替换。

我们的示例是用户开始自信地编写自己的存储过程的良好起点。

创建Cargo项目

在安装了必备条件后，按照以下步骤操作

1. 创建一个Cargo项目

$ cargo init --lib

2. 将以下行添加到 Cargo.toml

[package]
name = "easy"
version = "0.1.0"
edition = "2018"
# author, license, etc

[dependencies]
tarantool = "4.0"
serde = "1.0"

[lib]
crate-type = ["cdylib"]

3. 创建名为 init.lua 的服务器入口点，其脚本如下

box.cfg({listen = 3301})
box.schema.func.create('easy', {language = 'C', if_not_exists = true})
box.schema.func.create('easy.easy2', {language = 'C', if_not_exists = true})
box.schema.user.grant('guest', 'execute', 'function', 'easy', {if_not_exists = true})
box.schema.user.grant('guest', 'execute', 'function', 'easy.easy2', {if_not_exists = true})

要了解更多关于上述命令的信息，请查阅Tarantool文档中的语法和用法详情

• box.cfg();
• box.schema.func.create();
• box.schema.user.grant().

4. 编辑 lib.rs 文件并添加以下行

use tarantool::proc;

#[proc]
fn easy() {
    println!("hello world");
}

#[proc]
fn easy2() {
    println!("hello world -- easy2");
}

我们现在准备提供一些使用示例。我们将展示调用函数的三个难度级别，从基本用法示例（easy），到几个更复杂的共享库示例（harder 和 hardest）。此外，还会有读取和写入数据的单独示例。

基本用法示例

编译应用程序并启动服务器

$ cargo build
$ LUA_CPATH=target/debug/lib?.so tarantool init.lua

检查生成的 .so 文件是否位于之前指定的 LUA_CPATH 上，以便下一行能够正常工作。

尽管Rust和Lua布局约定不同，但我们可以利用Lua的灵活性，并通过显式设置LUA_CPATH环境变量来纠正它，如上所示。

现在你可以开始进行一些请求。打开一个新的控制台窗口并作为客户端运行Tarantool。将以下内容粘贴到控制台中

conn = require('net.box').connect(3301)
conn:call('easy')

如有必要，请查看net.box模块文档。

上面的代码建立了一个服务器连接并调用了'easy'函数。由于lib.rs中的easy()函数以println!("hello world")开始，"hello world"字符串将出现在服务器控制台输出中。

该代码还检查了调用是否成功。由于lib.rs中的easy()函数以return 0结束，没有错误消息要显示，请求已结束。

现在让我们调用lib.rs中的另一个函数，即easy2()。与easy()函数类似，但有一个区别：如果文件名与函数名不匹配，我们必须显式指定{file-name}.{function-name}。

conn:call('easy.easy2')

...这一次的结果将是hello world -- easy2。

正如你所看到的，调用Rust函数是非常直接的。

获取调用参数

创建一个名为"harder"的新crate。将以下行添加到lib.rs

#[tarantool::proc]
fn harder(fields: Vec<i32>) {
    println!("field_count = {}", fields.len());

    for val in fields {
        println!("val={}", val);
    }
}

上述代码定义了一个存储过程，该过程接受一系列整数。

使用 cargo build 将程序编译成 harder.so 库。

现在回到客户端，执行以下请求

box.schema.func.create('harder', {language = 'C'})
box.schema.user.grant('guest', 'execute', 'function', 'harder')
passable_table = {}
table.insert(passable_table, 1)
table.insert(passable_table, 2)
table.insert(passable_table, 3)
capi_connection:call('harder', {passable_table})

这次调用传递一个 Lua 表（passable_table）给 harder() 函数。该函数会检测到这是在我们上面示例的 args 部分编码的。

控制台输出现在应该如下所示

tarantool> capi_connection:call('harder', {passable_table})
field_count = 3
val=1
val=2
val=3
---
- []
...

如您所见，解码传递给 Rust 函数的参数值可能很复杂，因为它需要编写额外的程序。

访问 Tarantool 空间

创建一个名为 "hardest" 的新 crate。将这些行放入 lib.rs

use serde::{Deserialize, Serialize};

use tarantool::{
    proc,
    space::Space,
    tuple::{Encode, Tuple},
};

#[derive(Serialize, Deserialize)]
struct Row {
    pub int_field: i32,
    pub str_field: String,
}

impl Encode for Row {}

#[proc]
fn hardest() -> Tuple {
    let mut space = Space::find("capi_test").unwrap();
    let result = space.insert(&Row {
        int_field: 10000,
        str_field: "String 2".to_string(),
    });
    result.unwrap()
}

这次 Rust 函数执行以下操作

1. 通过调用 Space::find() 方法找到 capi_test 空间；
2. 在自动模式下将行结构序列化为一个元组；
3. 使用 .insert() 插入元组。

使用 cargo build 将程序编译成 hardest.so 库。

现在回到客户端，执行以下请求

box.schema.func.create('hardest', {language = "C"})
box.schema.user.grant('guest', 'execute', 'function', 'hardest')
box.schema.user.grant('guest', 'read,write', 'space', 'capi_test')
capi_connection:call('hardest')

此外，在客户端执行另一个请求

box.space.capi_test:select()

结果应该如下所示

tarantool> box.space.capi_test:select()
---
- - [10000, 'String 2']
...

上述证明 hardest() 函数已成功。

读取示例

创建一个名为 "read" 的新 crate。将这些行放入 lib.rs

use serde::{Deserialize, Serialize};

use tarantool::{
    proc,
    space::Space,
    tuple::Encode,
};

#[derive(Serialize, Deserialize, Debug)]
struct Row {
    pub int_field: i32,
    pub str_field: String,
}

impl Encode for Row {}

#[proc]
fn read() {
    let space = Space::find("capi_test").unwrap();

    let key = 10000;
    let result = space.get(&(key,)).unwrap();
    assert!(result.is_some());

    let result = result.unwrap().decode::<Row>().unwrap();
    println!("value={:?}", result);
}

上述代码执行以下操作

1. 通过调用 Space::find() 找到 capi_test 空间；
2. 使用 Rust 元组字面量（序列化结构的替代方案）格式化搜索键 = 10000；
3. 使用 .get() 获取元组；
4. 反序列化结果。

使用 cargo build 将程序编译成 read.so 库。

现在回到客户端，执行以下请求

box.schema.func.create('read', {language = "C"})
box.schema.user.grant('guest', 'execute', 'function', 'read')
box.schema.user.grant('guest', 'read,write', 'space', 'capi_test')
capi_connection:call('read')

capi_connection:call('read') 的结果应该如下所示

tarantool> capi_connection:call('read')
uint value=10000.
string value=String 2.
---
- []
...

上述证明 read() 函数已成功。

写入示例

创建一个名为 "write" 的新 crate。将这些行放入 lib.rs

use tarantool::{
    proc,
    error::Error,
    fiber::sleep,
    space::Space,
    transaction::transaction,
};

#[proc]
fn write() -> Result<(i32, String), String> {
    let mut space = Space::find("capi_test")
        .ok_or_else(|| "Can't find space capi_test".to_string())?;

    let row = (1, "22".to_string());

    transaction(|| -> Result<(), Error> {
        space.replace(&row)?;
        Ok(())
    })
    .unwrap();

    sleep(std::time::Duration::from_millis(1));
    Ok(row)
}

上述代码执行以下操作

1. 通过调用 Space::find() 找到 capi_test 空间；
2. 准备行值；
3. 启动事务；
4. 替换 box.space.capi_test 中的元组；
5. 完成事务
   • 在闭包接收到 Ok() 时执行提交；
   • 在接收到 Error() 时执行回滚；
6. 将整个元组返回给调用者，并让调用者显示它。

box.schema.func.create('write', {language = "C"})
box.schema.user.grant('guest', 'execute', 'function', 'write')
box.schema.user.grant('guest', 'read,write', 'space', 'capi_test')
capi_connection:call('write')

tarantool> capi_connection:call('write')
---
- [[1, '22']]
...

make
make test