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 = "5.0"

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

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

功能

• net_box - 启用协议实现（默认启用）
• schema - 启用模式操作工具（目前处于开发中）

存储过程

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 = "5.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_CPATH环境变量来掌握Lua的灵活性，如下所示。

现在你可以开始发送请求了。打开一个新的控制台窗口并运行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()函数相同，但有一个区别：如果文件名与函数名不匹配，我们必须明确指定 {文件名}.{函数名}。

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()函数。该harder()函数将检测到它，如我们上面的示例中编码在args部分。

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

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

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']
...

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

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')

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

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

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