Rust FFI不透明类型库ffi-opaque的使用：实现安全的跨语言接口与数据隐藏

什么是ffi-opaque

一个生成正确不透明类型的宏。

它的作用

在RFC 1861（外部类型）实现之前，在Rust中表示不透明结构体很困难，正如相应的Nomicon部分所述。

然而，不透明结构体是一种常见模式，特别是在通过FFI与C代码库一起工作时。

ffi-opaque提供了opaque!宏，可以正确生成这些类型，而无需考虑细节。

此宏生成的类型：

• 不能在定义它们的模块之外构造
• 确保正确的指针对齐
• 是!Send、!Sync、!Unpin
• 是FFI安全的

简而言之，它们尽可能接近地匹配外部类型的行为，正如目前在rustc中实现的那样。

当前差异：

• 生成的类型大小为0（而不是未调整大小）
• 生成的类型对齐为1（而不是未调整大小）
• 可以在它们上调用size_of_val和align_of_val

使用示例

考虑来自leveldb C API的这个示例：

typedef struct leveldb_options_t leveldb_options_t;
typedef struct leveldb_writeoptions_t leveldb_writeoptions_t;

leveldb_options_t* leveldb_options_create();
leveldb_writeoptions_t* leveldb_writeoptions_create();

它使用不透明结构体来避免将其数据库选项的结构细节泄漏到链接到它的库。我们可以像这样在Rust端表示不透明结构体：

use ffi_opaque::opaque;

opaque! {
    /// 文档有效！
    pub struct leveldb_options_t;
    /// 写入数据时使用的选项
    pub struct leveldb_writeoptions_t;
}

extern "C" {
    pub fn leveldb_options_create() -> *mut leveldb_options_t;
    pub fn leveldb_writeoptions_create() -> *mut leveldb_writeoptions_t;
}

可能的未来扩展

如果extern类型稳定，此宏可能会采用它们。

许可证

MIT，请参阅LICENSE文件。

致谢

• David Tolnay (@dtolnay) 提高了对许多微妙问题的认识
• Nikolai Vasquez (@nvzqz) 实现了最终类型和许多检查

完整示例代码

// 添加ffi-opaque依赖到Cargo.toml
// ffi-opaque = "2.0.1"

use ffi_opaque::opaque;

// 使用opaque!宏定义不透明类型
opaque! {
    /// 数据库选项类型
    pub struct leveldb_options_t;
    /// 写入选项类型
    pub struct leveldb_writeoptions_t;
}

// 声明外部C函数
extern "C" {
    pub fn leveldb_options_create() -> *mut leveldb_options_t;
    pub fn leveldb_writeoptions_create() -> *mut leveldb_writeoptions_t;
    pub fn leveldb_options_destroy(options: *mut leveldb_options_t);
    pub fn leveldb_writeoptions_destroy(options: *mut leveldb_writeoptions_t);
}

// 安全的Rust包装器
pub struct LevelDBOptions {
    ptr: *mut leveldb_options_t,
}

impl LevelDBOptions {
    pub fn new() -> Option<Self> {
        unsafe {
            let ptr = leveldb_options_create();
            if ptr.is_null() {
                None
            } else {
                Some(Self { ptr })
            }
        }
    }
}

impl Drop for LevelDBOptions {
    fn drop(&mut self) {
        unsafe {
            leveldb_options_destroy(self.ptr);
        }
    }
}

pub struct LevelDBWriteOptions {
    ptr: *mut leveldb_writeoptions_t,
}

impl LevelDBWriteOptions {
    pub fn new() -> Option<Self> {
        unsafe {
            let ptr = leveldb_writeoptions_create();
            if ptr.is_null() {
                None
            } else {
                Some(Self { ptr })
            }
        }
    }
}

impl Drop for LevelDBWriteOptions {
    fn drop(&mut self) {
        unsafe {
            leveldb_writeoptions_destroy(self.ptr);
        }
    }
}

// 示例使用
fn main() {
    let options = LevelDBOptions::new().expect("Failed to create options");
    let write_options = LevelDBWriteOptions::new().expect("Failed to create write options");
    
    // 使用选项...
    println!("LevelDB options and write options created successfully");
}

完整示例demo

// Cargo.toml依赖配置
// [dependencies]
// ffi-opaque = "2.0.1"

use ffi_opaque::opaque;
use std::ptr;

// 定义不透明类型
opaque! {
    /// LevelDB数据库配置选项
    pub struct leveldb_options_t;
    /// LevelDB写入操作选项
    pub struct leveldb_writeoptions_t;
}

// 声明外部C函数接口
extern "C" {
    // 创建数据库选项
    pub fn leveldb_options_create() -> *mut leveldb_options_t;
    // 创建写入选项
    pub fn leveldb_writeoptions_create() -> *mut leveldb_writeoptions_t;
    // 销毁数据库选项
    pub fn leveldb_options_destroy(options: *mut leveldb_options_t);
    // 销毁写入选项
    pub fn leveldb_writeoptions_destroy(options: *mut leveldb_writeoptions_t);
    // 设置创建数据库时如果目录不存在是否创建
    pub fn leveldb_options_set_create_if_missing(options: *mut leveldb_options_t, value: u8);
    // 设置错误日志级别
    pub fn leveldb_options_set_info_log(options: *mut leveldb_options_t, log: *const std::os::raw::c_void);
}

// 安全的数据库选项包装器
pub struct LevelDBOptions {
    ptr: *mut leveldb_options_t,
}

impl LevelDBOptions {
    /// 创建新的LevelDB选项实例
    pub fn new() -> Option<Self> {
        unsafe {
            let ptr = leveldb_options_create();
            if ptr.is_null() {
                None
            } else {
                Some(Self { ptr })
            }
        }
    }

    /// 设置如果目录不存在时创建数据库
    pub fn set_create_if_missing(&mut self, create: bool) {
        unsafe {
            leveldb_options_set_create_if_missing(self.ptr, create as u8);
        }
    }

    /// 获取原始指针（用于FFI调用）
    pub fn as_ptr(&self) -> *mut leveldb_options_t {
        self.ptr
    }
}

impl Drop for LevelDBOptions {
    fn drop(&mut self) {
        unsafe {
            leveldb_options_destroy(self.ptr);
        }
    }
}

// 安全的写入选项包装器
pub struct LevelDBWriteOptions {
    ptr: *mut leveldb_writeoptions_t,
}

impl LevelDBWriteOptions {
    /// 创建新的写入选项实例
    pub fn new() -> Option<Self> {
        unsafe {
            let ptr = leveldb_writeoptions_create();
            if ptr.is_null() {
                None
            } else {
                Some(Self { ptr })
            }
        }
    }

    /// 获取原始指针（用于FFI调用）
    pub fn as_ptr(&self) -> *mut leveldb_writeoptions_t {
        self.ptr
    }
}

impl Drop for LevelDBWriteOptions {
    fn drop(&mut self) {
        unsafe {
            leveldb_writeoptions_destroy(self.ptr);
        }
    }
}

// 数据库操作结构体（示例）
pub struct LevelDB {
    options: LevelDBOptions,
    write_options: LevelDBWriteOptions,
}

impl LevelDB {
    /// 创建新的LevelDB实例
    pub fn new() -> Option<Self> {
        let options = LevelDBOptions::new()?;
        let write_options = LevelDBWriteOptions::new()?;
        
        // 配置默认选项
        options.set_create_if_missing(true);
        
        Some(Self {
            options,
            write_options,
        })
    }

    /// 获取数据库选项
    pub fn options(&self) -> &LevelDBOptions {
        &self.options
    }

    /// 获取写入选项
    pub fn write_options(&self) -> &LevelDBWriteOptions {
        &self.write_options
    }
}

// 主函数示例
fn main() {
    // 创建LevelDB实例
    let leveldb = LevelDB::new().expect("Failed to create LevelDB instance");
    
    // 使用选项进行数据库操作
    println!("LevelDB instance created successfully");
    println!("Using options: {:?}", leveldb.options().as_ptr());
    println!("Using write options: {:?}", leveldb.write_options().as_ptr());
    
    // 这里可以添加实际的数据库操作代码
    // 例如：打开数据库、写入数据、读取数据等
    
    println!("LevelDB demo completed successfully");
}

// 单元测试
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_options_creation() {
        let options = LevelDBOptions::new();
        assert!(options.is_some(), "Options should be created successfully");
        
        let write_options = LevelDBWriteOptions::new();
        assert!(write_options.is_some(), "Write options should be created successfully");
    }

    #[test]
    fn test_options_configuration() {
        let mut options = LevelDBOptions::new().unwrap();
        options.set_create_if_missing(true);
        // 配置选项生效
    }

    #[test]
    fn test_leveldb_creation() {
        let leveldb = LevelDB::new();
        assert!(leveldb.is_some(), "LevelDB instance should be created successfully");
    }
}