Rust FFI 编程 - 手动绑定 C 库入门 05
Rust FFI 编程 - 手动绑定 C 库入门 05
本篇，咱们一起来研究 Rust 与 C 之间的回调函数传递。本篇的目标如下：
- 被调函数在 C 端，接收一个函数指针作为回调函数，并调用；
- 主函数在 Rust 中，在 Rust 中调用 C 端的这个函数；
- 在 Rust 中，传递一个 Rust 中定义的函数，到这个 C 端的被调函数中作为回调函数。
为什么要研究跨 FFI 的回调函数，因为
- 有可能想在底层事件（异步）框架中，注册一个函数，事件触发的时候，调用；
- 底层采用注册一个路由表的形式，在程序开始的时候，注册一堆函数操作进去；
- 其它。
这是一种常见需求，也是一种设计模式。
基础示例
话不多说，我们来设计一个示例流程：
- C 端，设计一个函数，sum_square_cb01， 接收两个整型参数 a, b，和一个函数指针，计算 a2 + b2 的值，并且将值传递进第三个参数（函数中），进行打印；
- Rust 端，定义一个回调函数 cb_func，在这个回调函数中，打印上述平方和；
- Rust 端，引入 C 中定义的 sum_square_cb01；
- 在 Rust 的 main 中，调用 sum_square_cb01。
好，直接上代码。C 端：
// csrc/ccode01.c
#include<stdio.h>
typedef void (*SumSquareCB)(int result);
void sum_square_cb01(int a, int b, SumSquareCB cb) {
int result = a*a + b*b;
cb(result);
}Rust 端：
// src/r01.rs
use std::os::raw::c_int;
pub type SumSquareCB = unsafe extern fn(c_int);
#[link(name = "ccode01")]
extern {
pub fn sum_square_cb01(a: c_int, b: c_int, cb: SumSquareCB);
}
pub unsafe extern fn cb_func(result: c_int) {
println!("The result in callback function is: {}", result);
}
fn main() {
unsafe {
sum_square_cb01(3, 4, cb_func);
}
}两边代码其实挺简洁。不过也有要注意的一些地方。要点提醒：
- 两边都需要定义回调函数的类型（签名），而且定义要一致。
C 中定义：
typedef void (*SumSquareCB)(int result);Rust 中定义：
pub type SumSquareCB = unsafe extern fn(c_int);fn 是 Rust 中的函数指针类型。具体可参见标准库文档 fn，解释得非常详尽。
函数指针的功能就是指向函数代码片断，可以用函数指针来调用函数，效果跟函数名一样，如上面 C 代码中的
cb(result)。
- Rust 中的回调函数定义
pub unsafe extern fn cb_func(result: c_int) {
println!("The result in callback function is: {}", result);
}是 Rust 中定义回调函数的代码，注意前面加的 unsafe 和 extern 修饰关键字。回调函数签名，要与前面定义的回调函数类型完全一致（此处接受一个整型参数，并且没有返回值）。
- 代码的编译方式，见前一篇，此不赘述。
运行
RUSTFLAGS='-L .' LD_LIBRARY_PATH="." cargo run --bin r01输出：
The result in callback function is: 25在回调函数中，更新外部数据
我们的上述代码（目前只有一条打印语句），可以适用于在回调函数中不需要改变外界数据的情况。而在实际情况下，我们使用的回调的逻辑，要求用回调更新一些程序中其它地方持有的数据，这种需求，使用上面的代码，就不能满足要求了。
我们很自然地想到了 C 中常用的全局变量大法。非常方便，无脑引用，并且这确实是可以实现的。但是，在 Rust 中，我们严重不推荐使用全局变量，故不举出全局变量的例子（防止只看片断的人，抄出不良风气）。
那我们这样行不行呢？
// src/r01-1.rs
use std::os::raw::c_int;
pub type SumSquareCB = unsafe extern fn(c_int);
#[link(name = "ccode01")]
extern {
pub fn sum_square_cb01(a: c_int, b: c_int, cb: SumSquareCB);
}
fn main() {
let mut sum = 0;
pub unsafe extern fn cb_func(result: c_int) {
sum += result;
}
unsafe {
sum_square_cb01(3, 4, cb_func);
}
println!("The result in callback function is: {}", sum);
}肯定是不行的。报如下错：
error[E0434]: can't capture dynamic environment in a fn item
--> src/r01-1.rs:14:9
|
14 | sum += result;
| ^^^
|
= help: use the `|| { ... }` closure form instead
error: aborting due to previous error提示这里应该用闭包。闭包跟函数还是不同的。闭包简单来说，由函数+被捕获的数据两大块儿组成。
那我们用闭包试试看：
// src/r01-2.rs
use std::os::raw::c_int;
pub type SumSquareCB = unsafe extern fn(c_int);
#[link(name = "ccode01")]
extern {
pub fn sum_square_cb01(a: c_int, b: c_int, cb: SumSquareCB);
}
fn main() {
let mut sum = 0;
unsafe {
sum_square_cb01(3, 4, |r| sum += r );
}
println!("The result in callback function is: {}", sum);
}编译，提示：
error[E0308]: mismatched types
--> src/r01-1.rs:14:31
|
14 | sum_square_cb01(3, 4, |r| sum += r );
| ^^^^^^^^^^^^ expected fn pointer, found closure
|
= note: expected fn pointer `unsafe extern "C" fn(i32)`
found closure `[closure@src/r01-1.rs:14:31: 14:43 sum:_]`
error: aborting due to previous error说这里类型不匹配。使用闭包，解决我们的问题，是肯定可以的。但是，需要有更多知识，我们专门放在下一节中讲解。本节，我们专注于用函数指针解决问题。
其实我们遇到的问题，在 C 的领域，早就是一种常见的问题（比如一个 GUI 库的回调函数），所以其实也早就有对应的解决方案，比如，使用 C 中的魔幻主义的 void * 携带一个数据块传递。了解过 void * 的就知道，它和 C 中的其它指针一起，几乎把 C 变成了一门动态语言（所以有一种说法认为 C 其实是弱类型语言？）。
void * 是一种通用指针，意思是”指向某个东西的指针“，它的灵活和强大之处在于，可以强制转换到任何指针类型。这里，我们也可以使用 void * 来传递我们的”数据块“。
有同学要问，为何不让回调函数直接返回一个值来达到我们想要实现的效果呢？所谓回调函数，一般处于调用链的末端，在这个函数里，实现对外部数据的更新。如果对返回值进行处理，则破坏了逻辑封装的抽象（需要在回调函数外写对应的逻辑代码，而回调函数外往往是框架代码）。
于是，我们继续规划一下我们的示例更新。在前面的基础之上：
- 在 Rust 的 main 函数中，定义一个变量 sum；
- 在 Rust 中定义的回调函数中，更新这个变量 sum；
- 由于需要传递数据块地址，需要修改回调函数的签名定义；
那我们直接上代码。
C端：
// csrc/ccode02.c
#include<stdio.h>
typedef void (*SumSquareCB)(int result, void *user_data);
void sum_square_cb02(int a, int b, SumSquareCB cb, void *user_data) {
int result = a*a + b*b;
cb(result, user_data);
}Rust 端：
use std::os::raw::c_int;
use std::ffi::c_void;
pub type SumSquareCB = unsafe extern fn(c_int, *mut c_void);
#[link(name = "ccode02")]
extern {
pub fn sum_square_cb02(a: c_int, b: c_int, cb: SumSquareCB, user_data: *mut c_void);
}
pub unsafe extern fn cb_func(result: c_int, user_data: *mut c_void) {
let data = &mut *(user_data as *mut c_int);
*data += result;
}
fn main() {
let mut sum = 0;
unsafe {
sum_square_cb02(
3,
4,
cb_func,
&mut sum as *mut c_int as *mut c_void);
}
println!("The sum is {}", sum);
}运行
RUSTFLAGS='-L .' LD_LIBRARY_PATH="." cargo run --bin r01输出：
The sum is 25要点：
- std::ffi::c_void
Rust 端引入了 std::ffi::c_void;。这是 Rust 给我们提供的强大的基础设施，不然我们真要愁眉苦脸了。从标准库页面可以学习到，Rust 中的 *const c_void 等于 C 的 const void*，Rust 中的 *mut c_void 等于 C 的 void*。（C 中的 void 函数返回值本身，与 Rust 的空值类型 () 相等）
请仔细体会上述代码中的各处 void * 与 *mut c_void 的写法和对应关系。
可以看到，void 指针就像一个万能的桥一样，让我们能够到处任意传递数据块。
- 回调函数中的类型强制转换
pub unsafe extern fn cb_func(result: c_int, user_data: *mut c_void) {
let data = &mut *(user_data as *mut c_int);
*data += result;
}前面提过，void * 的强大就在于可以与任意指针类型进行强制转换。在 Rust 也是对应的，也可以与任意指针类型强制转换。
let data = &mut *(user_data as *mut c_int);这一句，先是把 *mut c_void 指针转换成 *mut c_int 指针，然后用 * 取它的数据块，然后用 &mut 取这个数据块的可变引用，进入 Rust 的常规领域（标准使用模式）。
然后，
*data += result;就是更新数据块中的值了。
- 传参时的
unsafe {
sum_square_cb02(
3,
4,
cb_func,
&mut sum as *mut c_int as *mut c_void);
}这里：
&mut sum as *mut c_int as *mut c_void是上述转换过程的逆过程。先将 &mut sum（sum 的可变引用），转换成 *mut c_int（c_int 类型的指针），进而转换成 *mut c_void（通用指针）。
- 打印语句
本身中的打印语句，是在 Rust 的 main 函数中，打印的是 main 函数中定义的 sum（而第一例是在回调中打印的）。因此，可以看到，sum 的值，确实是在回调函数中，被修改过了。达到了我们的目的。
好了，我们的想法其实已经实现了。但是本例仅仅更新了一个整数，貌似没多大用。真实世界中，一般是更新一个结构体。那我们就更进一步，研究一下，怎么更新结构体。
其实非常简单。
更新结构体
同样直接上代码，然后再讲要点。
C 端：
#include<stdio.h>
typedef void (*SumSquareCB)(int result, void *user_data);
void sum_square_cb03(int a, int b, SumSquareCB cb, void *user_data) {
int result = a*a + b*b;
cb(result, user_data);
}Rust 端：
use std::os::raw::c_int;
use std::ffi::c_void;
pub type SumSquareCB = unsafe extern fn(c_int, *mut c_void);
#[link(name = "ccode03")]
extern {
pub fn sum_square_cb03(a: c_int, b: c_int, cb: SumSquareCB, user_data: *mut c_void);
}
pub unsafe extern fn cb_func(result: c_int, user_data: *mut c_void) {
let data = &mut *(user_data as *mut SumRecord);
data.sum += result;
data.elem_number += 1;
}
#[derive(Debug, Default, Clone, PartialEq)]
struct SumRecord {
sum: c_int,
elem_number: usize,
}
fn main() {
let mut sum = SumRecord::default();
unsafe {
sum_square_cb03(
3,
4,
cb_func,
&mut sum as *mut SumRecord as *mut c_void);
}
println!("The sum is {:?}", sum);
}运行：
RUSTFLAGS='-L .' LD_LIBRARY_PATH="." cargo run --bin r03输出：
The sum is SumRecord { sum: 25, elem_number: 1 }解析：
- C 中代码没变
可以看到，其实 C 中代码没有变化。
- Rust 中加了结构体定义
#[derive(Debug, Default, Clone, PartialEq)]
struct SumRecord {
sum: c_int,
elem_number: usize,
}就是一个普通的 Rust 结构体定义。
- 魔法在哪里？
Rust 中的回调函数签名都没有变化。变化在下面这里：
let data = &mut *(user_data as *mut SumRecord);
data.sum += result;
data.elem_number += 1;可以看到，就是把例 2 中的 *mut c_int 变成了 *mut SumRecord 了。然后，更新数据的时候，按 Rust 结构体更新的方式操作就可以了。
unsafe {
sum_square_cb03(
3,
4,
cb_func,
&mut sum as *mut SumRecord as *mut c_void);
}同样，这个逆过程也变化了，仔细体会。
就这样，我们就实现了在回调函数中，更新外部结构体。达成我们的理想要求。
总结
在本篇，我们研究了 Rust 与 C 如何跨 FFI 边界实现回调函数的调用，以及在回调中更新外部数据。全篇内容，主要参考：
- http://adventures.michaelfbryan.com/posts/rust-closures-in-ffi/ 感谢作者的精彩分享
- Rust 标准库文档
文章中的代码在：https://github.com/daogangtang/learn-rust/tree/master/09rustffi2