Rust高性能插件库z32的使用指南

z32简介

z32是一个专为Rust设计的高性能插件库，提供了高效的扩展功能和定制化开发支持。它特别适合需要动态加载和卸载功能模块的应用场景，如游戏引擎、数据分析平台或需要热更新的服务。

主要特性

• 高性能插件加载和卸载机制
• 低开销的插件间通信
• 内存安全保证
• 跨平台支持
• 灵活的定制化开发接口

基本使用方法

1. 添加依赖

首先在Cargo.toml中添加z32依赖：

[dependencies]
z32 = "0.4.2"

2. 创建插件

// my_plugin.rs
use z32::{Plugin, PluginResult};

#[derive(Default)]
struct MyPlugin;

impl Plugin for MyPlugin {
    fn name(&self) -> &str {
        "MyPlugin"
    }

    fn execute(&self, input: &[u8]) -> PluginResult<Vec<u8>> {
        let output = input.iter().map(|b| b + 1).collect();
        Ok(output)
    }
}

// 必须导出这个函数
#[no_mangle]
pub fn _create_plugin() -> Box<dyn Plugin> {
    Box::new(MyPlugin::default())
}

3. 加载和使用插件

use z32::{PluginManager, Plugin};
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut manager = PluginManager::new();
    
    // 加载插件
    manager.load(Path::new("target/debug/libmy_plugin.so"))?;
    
    // 获取插件实例
    let plugin = manager.get_plugin("MyPlugin").unwrap();
    
    // 使用插件
    let input = vec![1, 2, 3];
    let output = plugin.execute(&input)?;
    
    println!("Plugin output: {:?}", output); // 输出: [2, 3, 4]
    
    // 卸载插件
    manager.unload("MyPlugin")?;
    
    Ok(())
}

高级功能

插件间通信

// 在插件A中注册服务
impl Plugin for PluginA {
    fn register_services(&self, registry: &mut ServiceRegistry) {
        registry.register("data_processor", Box::new(DataProcessor::new()));
    }
}

// 在插件B中使用服务
impl Plugin for PluginB {
    fn execute(&self, _: &[u8]) -> PluginResult<Vec<u8>> {
        if let Some(processor) = self.get_service::<DataProcessor>("data_processor") {
            let result = processor.process_data();
            // ...
        }
        Ok(vec![])
    }
}

热重载示例

use std::time::Duration;
use notify::{RecommendedWatcher, Watcher, RecursiveMode};

fn watch_and_reload(manager: &mut PluginManager, path: &Path) -> notify::Result<()> {
    let (tx, rx) = std::sync::mpsc::channel();
    let mut watcher: RecommendedWatcher = Watcher::new(tx, Duration::from_secs(1))?;
    watcher.watch(path, RecursiveMode::NonRecursive)?;

    for event in rx {
        if let notify::Event { kind: notify::EventKind::Modify(_), .. } = event {
            println!("Detected plugin change, attempting reload...");
            let plugin_name = "MyPlugin";
            manager.unload(plugin_name)?;
            manager.load(path)?;
            println!("Plugin reloaded successfully");
        }
    }
    Ok(())
}

性能优化建议

1. 尽量减少插件间的数据拷贝，使用共享内存或引用计数
2. 对频繁调用的插件函数，考虑使用零拷贝技术
3. 合理设置插件的生命周期，避免频繁加载卸载
4. 使用z32提供的性能分析工具监控插件性能

注意事项

• 插件和主程序需要使用相同的Rust版本编译
• 在Windows上使用.dll，Linux上使用.so，macOS上使用.dylib
• 确保插件和主程序使用的所有共享依赖版本一致

完整示例代码

下面是一个完整的z32使用示例，包含主程序和插件实现：

插件实现 (my_plugin.rs)

// 导入必要的模块
use z32::{Plugin, PluginResult};

// 定义插件结构体
#[derive(Default)]
pub struct MyPlugin;

// 实现Plugin trait
impl Plugin for MyPlugin {
    // 返回插件名称
    fn name(&self) -> &str {
        "MyPlugin"
    }

    // 执行插件功能 - 简单的字节数组处理
    fn execute(&self, input: &[u8]) -> PluginResult<Vec<u8>> {
        // 对每个字节加1
        let output = input.iter().map(|b| b.wrapping_add(1)).collect();
        Ok(output)
    }
}

// 必须导出的插件创建函数
#[no_mangle]
pub fn _create_plugin() -> Box<dyn Plugin> {
    Box::new(MyPlugin::default())
}

主程序 (main.rs)

use z32::{PluginManager, Plugin};
use std::path::Path;
use std::time::Duration;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建插件管理器
    let mut manager = PluginManager::new();
    
    // 插件路径 - 注意根据平台使用正确的扩展名
    let plugin_path = Path::new("target/debug/libmy_plugin.so");
    
    // 加载插件
    println!("Loading plugin...");
    manager.load(plugin_path)?;
    
    // 获取插件实例
    let plugin = manager.get_plugin("MyPlugin").expect("Plugin not found");
    
    // 测试插件功能
    let test_data = vec![10, 20, 30, 40];
    println!("Testing plugin with input: {:?}", test_data);
    
    // 执行插件
    let result = plugin.execute(&test_data)?;
    println!("Plugin result: {:?}", result);
    
    // 模拟热重载场景
    println!("Simulating hot reload...");
    manager.unload("MyPlugin")?;
    manager.load(plugin_path)?;
    println!("Hot reload completed");
    
    // 再次测试插件
    let plugin = manager.get_plugin("MyPlugin").unwrap();
    let result = plugin.execute(&[99, 100, 101])?;
    println!("After reload, result: {:?}", result);
    
    // 清理插件
    manager.unload("MyPlugin")?;
    println!("Plugin unloaded");
    
    Ok(())
}

Cargo.toml 配置

[package]
name = "z32-example"
version = "0.1.0"
edition = "2021"

[lib]
name = "my_plugin"
crate-type = ["cdylib"]  # 重要：必须设置为cdylib才能生成动态库

[dependencies]
z32 = "0.4.2"

构建和运行步骤

1. 首先构建插件库：

cargo build --lib

1. 然后运行主程序：

cargo run

1. 预期输出：

Loading plugin...
Testing plugin with input: [10, 20, 30, 40]
Plugin result: [11, 21, 31, 41]
Simulating hot reload...
Hot reload completed
After reload, result: [100, 101, 102]
Plugin unloaded

这个完整示例展示了z32的核心功能，包括插件创建、加载、执行和热重载。您可以根据实际需求扩展这个基础框架。