外部函数接口(FFI)#

类型#

类型是 Rust 确保内存安全的方式. 当与其他可能不提供相同保证的语言进行接口时, 绑定中类型的选择对于维护内存安全至关重要.

数据布局#

Rust 在内存中布局数据的方式没有短期或长期的保证. 使数据与外部语言兼容的唯一方法是通过使用 repr 属性明确使用 C 兼容的数据布局(参见 Rust 参考: 类型布局). 例如, 以下 Rust 类型:

#[repr(C)]
struct Data {
    a: u32,
    b: u16,
    c: u64,
}
#[repr(C, packed)]
struct PackedData {
    a: u32,
    b: u16,
    c: u64,
}

与以下 C 类型兼容:

struct Data {
    uint32_t a;
    uint16_t b;
    uint64_t c;
};
__attribute__((packed))
struct PackedData {
    uint32_t a;
    uint16_t b;
    uint64_t c;
}

TIP

规则 在 FFI 中仅使用 C 兼容的类型#

在安全的 Rust 开发中, 导入或导出函数的参数或返回类型以及导入或导出全局变量的类型必须仅使用 C 兼容的类型.

唯一的例外是在外部一侧被认为是不透明的类型.

以下类型被认为是 C 兼容的:

• 整数或浮点原始类型,
• 使用 repr(C) 注释的 struct,
• 具有至少一个变体且只有无字段变体的 repr(C) 或 repr(Int) 注释的 enum(其中 Int 是整数原始类型),
• 指针.

以下类型不是 C 兼容的:

• 动态大小类型,
• Trait 对象,
• 带有字段的枚举,
• 元组(但 repr(C) 元组结构是可以的).

某些类型是兼容的, 但有一些注意事项:

• 确实是零大小的零大小类型(在 C 中未指定, 并且与 C++ 规范相矛盾),
• 带有字段的 repr(C)、repr(C, Int) 或 repr(Int) 注释的枚举(参见 RFC 2195).

类型一致性#

NOTE

规则 在 FFI 边界使用一致的类型#

类型在 FFI 边界的每一侧必须保持一致.

尽管某些细节可能在一侧相对于另一侧被隐藏(通常是为了使类型不透明), 但两侧的类型必须具有相同的大小和相同的对齐要求.

特别是对于带有字段的枚举, C(或 C++)中的相应类型并不明显, 详见 RFC 2195.

自动生成绑定的自动化工具, 如 rust-bindgen 或 cbindgen, 可以帮助确保在 C 和 Rust 之间的类型一致.

NOTE

建议 使用自动生成绑定的工具#

在安全的 Rust 开发中, 应尽可能使用自动生成工具来生成绑定, 并持续地维护它们.

CAUTION

警告#

对于将 C/C++ 绑定到 Rust, rust-bindgen 能够自动生成低级绑定. 强烈建议使用高级别安全绑定(参见建议 FFI-SAFEWRAPPING). 此外, rust-bindgen 的某些选项可能会导致危险的转换, 特别是 rustified_enum.

平台相关类型#

当与外部语言(如 C 或 C++)进行接口时, 通常需要使用平台相关类型, 如 C 的 int、long 等.

除了 std::ffi(或 core::ffi)中的 c_void 代表 void 外, 标准库还在 std:os::raw(或 core::os::raw)中提供了可移植的类型别名:

• c_char 代表 char(可以是 i8 或 u8),
• c_schar 代表 signed char(始终为 i8),
• c_uchar 代表 unsigned char(始终为 u8),
• c_short 代表 short,
• c_ushort 代表 unsigned short,
• c_int 代表 int,
• c_uint 代表 unsigned int,
• c_long 代表 long,
• c_ulong 代表 unsigned long,
• c_longlong 代表 long long,
• c_ulonglong 代表 unsigned long long,
• c_float 代表 float(始终为 f32),
• c_double 代表 double(始终为 f64).

[libc] crate 提供了更多与 C 兼容的类型, 几乎完全涵盖了 C 标准库.

NOTE

规则 绑定到平台相关类型时使用可移植别名 c_*#

在安全的 Rust 开发中, 当与使用平台相关类型(如 C 的 int 和 long)的外部代码进行接口时, Rust 代码必须使用可移植类型别名, 如标准库或 libc crate 提供的, 而不是平台特定类型, 除非对每个平台自动生成了绑定(见下面的注意).

CAUTION

注意#

自动绑定生成工具(如 cbindgen、rust-bindgen)能够确保特定平台上的类型一致性. 在构建过程中, 应针对每个目标使用这些工具, 以确保生成对特定目标平台有效的代码.

非健壮类型: 引用、函数指针、枚举#

特定类型的 陷阱表示 是符合该类型表示约束(如大小和对齐)但不代表该类型有效值的表示(位模式), 并导致未定义行为.

简而言之, 如果将 Rust 变量设置为这样的无效值, 可能会发生从简单的程序崩溃到任意代码执行的任何情况. 在编写安全的 Rust 代码时, 这是不可能的(除非 Rust 编译器中存在错误). 但是, 在编写不安全的 Rust 代码, 特别是在 FFI 中, 情况就不一样了.

在下面, 非健壮类型 是具有这种陷阱表示的类型(至少有一个). 许多 Rust 类型都是非健壮的, 即使在 C 兼容类型中也是如此:

• bool(1 字节, 256 种表示, 只有 2 种有效的),
• 引用,
• 函数指针,
• 枚举,
• 浮点数(即使几乎每种语言对于什么是有效的浮点数都有相同的理解),
• 包含非健壮类型字段的复合类型.

另一方面, 整数类型(u*/i*)、不包含非健壮字段的紧凑复合类型, 它们的实例都是健壮类型.

非健壮类型在两种语言之间进行接口时是一个困难. 它涉及决定两种语言中哪一种负责断言跨界值的有效性以及如何做到这一点.

NOTE

建议 在 Rust 中检查外部值#

在安全的 Rust 开发中, 应尽可能在 Rust 中对外部值的有效性进行检查.

这些通用规则应根据特定的外部语言或相关风险进行调整. 就语言而言, C 特别不适合提供关于有效性的保证. 然而, Rust 并不是唯一提供强大保证的语言. 例如, 某些 C++ 子集(不包括重新解释)允许开发人员进行大量类型检查. 因为 Rust 本身将安全和不安全的部分分开, 所以推荐始终在可能的情况下使用 Rust 进行检查. 至于风险, 最危险的类型是引用、函数引用和枚举, 下面将对其进行讨论.

CAUTION

警告#

Rust 的 bool 已经被定义为等同于 C99 的 _Bool(在 <stdbool.h> 中别名为 bool)和 C++ 的 bool. 但是, 在 _Bool/bool 中加载除 0 和 1 以外的值是 在两侧 都是未定义行为的. 安全的 Rust 确保了这一点. 符合标准的 C 和 C++ 编译器确保除 0 和 1 以外的值不会 存储 在 _Bool/bool 值中, 但不能保证不存在 不正确的重新解释(例如, 联合类型、指针转换). 为了检测这种错误的重新解释, 可以使用诸如 LLVM 的 -fsanitize=bool 等工具.

/// 就地相加
#[no_mangle]
pub unsafe extern fn add_in_place(a: *mut u32, b: u32) {
    // 检查 `a` 是否为空
    // 如果非空, 则获取可变引用
    if let Some(a) = a.as_mut() {
        *a += b
    }
}

#include <stdint.h>
#include <inttypes.h>

//! 就地相加
void add_in_place(uint32_t *a, uint32_t b);

int main() {
    uint32_t x = 25;
    add_in_place(&x, 17);
    printf("%" PRIu32 " == 42", x);
    return 0;
}

uint32_t repeat(uint32_t start, uint32_t n, uint32_t (*f)(uint32_t));

不透明类型#

使类型不透明是增加软件开发中模块化的一种良好方法. 在进行多语言开发时, 这是非常常见的.

NOTE

建议 对外部不透明类型使用专用的 Rust 类型#

在安全的 Rust 开发中, 绑定外部不透明类型时, 应使用指向专用不透明类型的指针, 而不是 c_void 指针.

目前, 制作外部不透明类型的推荐方法如下:

#[repr(C)]
pub struct Foo {_private: [u8; 0]}
extern "C" {
    fn foo(arg: *mut Foo);
}

尚未实现的 RFC 1861 提议通过允许在 extern 块中声明不透明类型来简化编码.

NOTE

建议 使用不完整的 C/C++#

struct 指针使类型不透明

在安全的 Rust 开发中, 当与 C 或 C++ 进行交互时, Rust 类型在 C/C++ 中应被视为不透明应该被翻译为不完整的 struct 类型(即, 没有定义声明)并且应该提供专用的构造函数和析构函数.

不透明 Rust 类型的示例:

# use std::panic::catch_unwind;
#
struct Opaque {
    // (...) 隐藏的细节
}

#[no_mangle]
pub unsafe extern "C" fn new_opaque() -> *mut Opaque {
    catch_unwind(|| // 捕获 panic, 见下文
        Box::into_raw(Box::new(Opaque {
            // (...) 实际构造
        }))
    ).unwrap_or(std::ptr::null_mut())
}

#[no_mangle]
pub unsafe extern "C" fn destroy_opaque(o: *mut Opaque) {
    catch_unwind(||
        if !o.is_null() {
            drop(Box::from_raw(o))
        }
    ); // 仅在 Opaque 或其子字段是 Drop 时需要
}

内存和资源管理#

编程语言以各种方式处理内存. 因此, 在 Rust 和另一种语言之间传输数据时, 了解哪种语言负责为这些数据回收内存空间非常重要. 对于其他类型的资源, 例如套接字或文件, 情况也是如此.

Rust 跟踪变量所有权和生命周期, 以确定在编译时是否以及何时应该释放内存. 借助 Drop trait, 可以利用这个系统来回收其他类型的资源, 例如文件或网络访问. 将某些数据从 Rust 移动到另一种语言意味着也放弃了与之关联的可能的回收.

NOTE

规则 在 FFI 边界不要使用实现 Drop 的类型#

在安全的 Rust 开发中, Rust 代码不得为直接传输到外部代码的任何类型实现 Drop(即不通过指针或引用).

实际上, 建议只使用 Copy 类型. 请注意, 即使 T 不是 Copy 类型, *const T 也是 Copy 类型.

然而, 如果不释放内存和资源是不好的, 那么使用已释放的内存或多次释放一些资源就更糟糕了, 从安全性的角度来看. 为了正确释放资源仅一次, 必须知道哪种语言负责分配和释放内存.

NOTE

规则 在 FFI 中确保明确的数据所有权#

在安全的 Rust 开发中, 当某种类型的数据在 FFI 边界上无需复制地传递时, 必须确保:

• 一个语言负责数据的分配和释放.
• 另一种语言不能直接分配或释放数据, 而是使用所选语言提供的专用外部函数.

拥有权还不够. 仍然需要确保正确的生命周期, 主要是在回收后不会发生使用. 这是一个更具挑战性的任务. 当另一种语言负责内存时, 最好的方法是在外部类型周围提供一个安全的包装器:

NOTE

建议 在内存释放包装器中封装外部数据#

在安全的 Rust 开发中, 应该将在外部语言中分配和释放的任何非敏感外部数据封装在 Drop 类型中, 以便通过自动调用外部语言的释放例程自动在 Rust 中释放它们.

CAUTION

警告#

因为恐慌可能导致未运行 Drop::drop 方法, 所以该解决方案对于敏感的资源释放(例如擦除敏感数据)并不足够, 除非可以保证代码永远不会发生恐慌.

对于擦除敏感数据的情况, 可以通过专用的恐慌处理程序来解决该问题.

当外部语言是利用 Rust 分配的资源时, 要提供任何保证就要困难得多.

例如, 在 C 中, 没有一种简单的方法可以检查是否已检查了适当的析构函数. 一种可能的方法是利用回调来确保回收是安全的.

以下 Rust 代码是一个线程不安全的示例, 展示了一个与 C 兼容的 API, 提供回调以确保安全的资源回收:

use std::ops::Drop;

pub struct XtraResource {/*fields */}

impl XtraResource {
    pub fn new() -> Self {
        XtraResource { /* ... */}
    }
    pub fn dosthg(&mut self) {
        /*...*/
    }
}

impl Drop for XtraResource {
    fn drop(&mut self) {
        println!("xtra drop");
    }
}

pub mod c_api {
    use super::XtraResource;
    use std::panic::catch_unwind;

    const INVALID_TAG: u32 = 0;
    const VALID_TAG: u32 = 0xDEAD_BEEF;
    const ERR_TAG: u32 = 0xDEAF_CAFE;

    static mut COUNTER: u32 = 0;

    pub struct CXtraResource {
        tag: u32, // to detect accidental reuse
        id: u32,
        inner: XtraResource,
    }

    #[no_mangle]
    pub unsafe extern "C" fn xtra_with(cb: extern "C" fn(*mut CXtraResource) -> ()) {
        let inner = if let Ok(res) = catch_unwind(XtraResource::new) {
            res
        } else {
#             println!("cannot allocate resource");
            return;
        };
        let id = COUNTER;
        let tag = VALID_TAG;

        COUNTER = COUNTER.wrapping_add(1);
        // Use heap memory and do not provide pointer to stack to C code!
        let mut boxed = Box::new(CXtraResource { tag, id, inner });

#         println!("running the callback on {:p}", boxed.as_ref());
        cb(boxed.as_mut() as *mut CXtraResource);

        if boxed.id == id && (boxed.tag == VALID_TAG || boxed.tag == ERR_TAG) {
#             println!("freeing {:p}", boxed.as_ref());
            boxed.tag = INVALID_TAG; // prevent accidental reuse
                                 // implicit boxed drop
        } else {
#             println!("forgetting {:p}", boxed.as_ref());
            // (...) error handling (should be fatal)
            boxed.tag = INVALID_TAG; // prevent reuse
            std::mem::forget(boxed); // boxed is corrupted it should not be
        }
    }

    #[no_mangle]
    pub unsafe extern "C" fn xtra_dosthg(cxtra: *mut CXtraResource) {
        let do_it = || {
            if let Some(cxtra) = cxtra.as_mut() {
                if cxtra.tag == VALID_TAG {
#                     println!("doing something with {:p}", cxtra);
                    cxtra.inner.dosthg();
                    return;
                }
            }
            println!("doing nothing with {:p}", cxtra);
        };
        if catch_unwind(do_it).is_err() {
            if let Some(cxtra) = cxtra.as_mut() {
#                 println!("panicking with {:p}", cxtra);
                cxtra.tag = ERR_TAG;
            }
        };
    }
}

兼容的 C 调用:

struct XtraResource;
void xtra_with(void (*cb)(XtraResource* xtra));
void xtra_sthg(XtraResource* xtra);

void cb(XtraResource* xtra) {
    // ()...) do anything with the proposed C API for XtraResource
    xtra_sthg(xtra);
}

int main() {
    xtra_with(cb);
}

处理 FFI 绑定的 Rust 代码中的 panic 对于保持稳定性并防止未定义行为至关重要. 当 Rust 代码从另一种语言(如 C)调用时, 任何 panic 必须得到适当处理, 以避免将 unwinding 传播到外部代码中. Rust 中的 panic! 宏是一个强大的错误信号工具, 但在 FFI 场景中必须控制其使用.

在提供的 Rust 代码片段中, may_panic 函数根据某些条件随机发生 panic. 为了确保可以从外部代码安全调用此函数, 它被包装在一个 catch_unwind 块中. 该块尝试捕获 may_panic 中发生的任何 panic, 防止它们传播到外部代码中. 相反, 如果发生 panic, 则返回错误代码(-1).

对于 #![no_std] 程序, 其中标准库不可用, 定义自定义 panic 处理程序是必需的. 此 panic 处理程序应以确保程序安全性和安全性的方式处理 panic. 或者, 可以使用类似 panic-never 的库来静态地确保代码中不会发生 panic.

在 Rust 中绑定外部库时, 建议提供两个部分: 一个密切反映原始 C API 的低级绑定和一个更高级的安全包装模块. 低级绑定应使用 extern 块忠实地转换 C API, 而安全包装模块应确保 Rust 级别的内存安全性和安全性不变量. 这种分离有助于在 Rust 和外部代码之间保持清晰度和安全性.

使用诸如 rust-bindgen 之类的工具可以自动生成从 C 头文件到低级绑定的代码, 简化与外部库交互的过程. 遵循这些最佳实践, 开发人员可以确保其 FFI 绑定的 Rust 代码保持强大、稳定和安全.

在另一种语言中绑定 Rust 库#

一个导出为 C 的 Rust 库的最简示例#

src/lib.rs:

/// 不透明的计数器
pub struct Counter(u32);

impl Counter {
    /// 创建一个计数器(初始值为 0)
    fn new() -> Self {
        Self(0)
    }
    /// 获取计数器当前值
    fn get(&self) -> u32 {
        self.0
    }
    /// 如果没有溢出, 则增加计数器的值
    fn incr(&mut self) -> bool {
        if let Some(n) = self.0.checked_add(1) {
            self.0 = n;
            true
        } else {
            false
        }
    }
}

// C 兼容 API

#[no_mangle]
pub unsafe extern "C" fn counter_create() -> *mut Counter {
    Box::into_raw(Box::new(Counter::new()))
}

#[no_mangle]
pub unsafe extern "C" fn counter_incr(counter: *mut Counter) -> std::os::raw::c_int {
    if let Some(counter) = counter.as_mut() {
        if counter.incr() {
            0
        } else {
            -1
        }
    } else {
        -2
    }
}

#[no_mangle]
pub unsafe extern "C" fn counter_get(counter: *const Counter) -> u32 {
    if let Some(counter) = counter.as_ref() {
        return counter.get();
    }
    return 0;
}

#[no_mangle]
pub unsafe extern fn counter_destroy(counter: *mut Counter) -> std::os::raw::c_int {
    if !counter.is_null() {
        let _ = Box::from_raw(counter); // 取出 box 并释放
        return 0;
    }
    return -1;
}

使用 cbindgen([cbindgen] -l c > counter.h), 可以生成一个一致的 C 头文件 counter.h:

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

typedef struct Counter Counter;

Counter *counter_create(void);

int counter_destroy(Counter *counter);

uint32_t counter_get(const Counter *counter);

int counter_incr(Counter *counter);

counter_main.c:

#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <inttypes.h>

#include "counter.h"

int main(int argc, const char** argv) {
    if (argc < 2) {
        return -1;
    }
    size_t n = (size_t)strtoull(argv[1], NULL, 10);

    Counter* c = counter_create();
    for (size_t i=0; i < n; i++) {
        if (counter_incr(c) != 0) {
            printf("overflow\n");
            counter_destroy(c);
            return -1;
        }
    }

    printf("%" PRIu32 "\n", counter_get(c));
    counter_destroy(c);

    return 0;
}