零拷贝序列化使用指南

📋 概述

本文档描述 qaexchange-rs 中的零拷贝（zero-copy）、零成本（zero-cost）和写时复制（copy-on-write）序列化模式。

🎯 核心设计原则

1. Zero-Copy（零拷贝）

定义：数据在传递过程中不进行深拷贝，直接共享内存。

实现：

• 使用 Arc<T> 包装共享数据（如 Arc<str>）
• 使用 rkyv 零拷贝反序列化（直接内存映射）
• 通过 mpsc 通道传递 Arc 指针

示例：

#![allow(unused)]
fn main() {
// ❌ 深拷贝（避免）
let notification_copy = notification.clone();  // 复制所有字段

// ✅ 零拷贝（推荐）
let notification_shared = Arc::new(notification);
let notification_ref = notification_shared.clone();  // 仅复制 Arc 指针
}

2. Zero-Cost（零成本）

定义：抽象层不引入运行时开销。

实现：

• 使用 #[repr(C)] 确保内存布局稳定
• 使用 #[inline] 提示编译器内联优化
• 避免动态分派（使用静态分派）

示例：

#![allow(unused)]
fn main() {
// src/notification/message.rs
#[derive(Archive, Serialize, Deserialize)]
#[archive(check_bytes)]
pub struct Notification {
    pub message_id: Arc<str>,  // Arc 是零成本抽象
    pub priority: u8,           // 直接存储，无装箱
    // ...
}
}

3. Copy-on-Write（写时复制）

定义：多个引用共享同一数据，仅在修改时才复制。

实现：

• 使用 Arc 实现不可变共享
• 使用 Cow<'a, T> 实现延迟复制
• 内部使用 &'static str 避免分配

示例：

#![allow(unused)]
fn main() {
// ✅ Copy-on-Write 模式
pub struct NotificationType {
    pub source: &'static str,  // 静态字符串，零分配
}

impl NotificationType {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::OrderAccepted => "order_accepted",  // 无需分配
            // ...
        }
    }
}
}

🚀 rkyv 零拷贝序列化

基本使用

1. 添加依赖

# Cargo.toml
[dependencies]
rkyv = { version = "0.7", default-features = false, features = ["validation", "alloc", "size_64", "bytecheck", "std"] }

2. 定义可序列化结构

#![allow(unused)]
fn main() {
use rkyv::{Archive, Deserialize as RkyvDeserialize, Serialize as RkyvSerialize};
use std::sync::Arc;

#[derive(Archive, RkyvSerialize, RkyvDeserialize)]
#[archive(check_bytes)]
pub struct Notification {
    pub message_id: Arc<str>,    // ✅ rkyv 原生支持 Arc
    pub user_id: Arc<str>,
    pub priority: u8,
    pub timestamp: i64,
    pub source: String,          // ⚠️ &'static str 不支持，改用 String
}
}

3. 序列化与反序列化

#![allow(unused)]
fn main() {
impl Notification {
    /// 序列化为 rkyv 字节流
    pub fn to_rkyv_bytes(&self) -> Result<Vec<u8>, String> {
        rkyv::to_bytes::<_, 1024>(self)
            .map(|bytes| bytes.to_vec())
            .map_err(|e| format!("Serialization failed: {}", e))
    }

    /// 零拷贝反序列化（带验证）
    pub fn from_rkyv_bytes(bytes: &[u8]) -> Result<&ArchivedNotification, String> {
        rkyv::check_archived_root::<Notification>(bytes)
            .map_err(|e| format!("Deserialization failed: {}", e))
    }

    /// 零拷贝反序列化（不验证，性能更高）
    pub unsafe fn from_rkyv_bytes_unchecked(bytes: &[u8]) -> &ArchivedNotification {
        rkyv::archived_root::<Notification>(bytes)
    }

    /// 完整反序列化（分配内存）
    pub fn from_archived(archived: &ArchivedNotification) -> Result<Self, String> {
        use rkyv::Deserialize;
        let mut deserializer = rkyv::de::deserializers::SharedDeserializeMap::new();
        archived.deserialize(&mut deserializer)
            .map_err(|e| format!("Failed: {:?}", e))
    }
}
}

访问归档数据

#![allow(unused)]
fn main() {
// 序列化
let notification = Notification::new(...);
let bytes = notification.to_rkyv_bytes()?;

// 零拷贝反序列化
let archived = Notification::from_rkyv_bytes(&bytes)?;

// ✅ 访问基本类型字段（需使用 from_archived! 宏）
assert_eq!(rkyv::from_archived!(archived.priority), 1);
assert_eq!(rkyv::from_archived!(archived.timestamp), 1728123456789);

// ✅ 访问 Arc<str> 字段（可直接访问）
assert_eq!(archived.user_id.as_ref(), "user_01");
}

📊 性能对比

Benchmark 结果

运行 cargo bench --bench notification_serialization：

关键洞察：

• ✅ 零拷贝反序列化快 25 倍（vs JSON）
• ✅ 零内存分配（反序列化时）
• ✅ 适合高频消息传递

批量序列化（10,000 条消息）

🔒 线程安全

Send + Sync 验证

#![allow(unused)]
fn main() {
#[test]
fn test_notification_thread_safety() {
    // 验证 Notification 实现了 Send + Sync
    fn assert_send_sync<T: Send + Sync>() {}
    assert_send_sync::<Notification>();
    assert_send_sync::<Arc<Notification>>();
}
}

Broker 中的线程安全传递

#![allow(unused)]
fn main() {
// src/notification/broker.rs

pub struct NotificationBroker {
    /// ✅ 使用 DashMap 实现无锁并发访问
    user_gateways: DashMap<Arc<str>, Vec<Arc<str>>>,

    /// ✅ 使用 mpsc 通道传递 Notification（必须是 Send）
    gateway_senders: DashMap<Arc<str>, mpsc::UnboundedSender<Notification>>,

    /// ✅ 使用 ArrayQueue 实现无锁优先级队列
    priority_queues: [Arc<ArrayQueue<Notification>>; 4],
}

/// 发布通知（多线程安全）
pub fn publish(&self, notification: Notification) -> Result<(), String> {
    // 1. Arc clone（零拷贝）
    let priority = notification.priority.min(3) as usize;
    self.priority_queues[priority].push(notification.clone())?;

    // 2. 通过 mpsc 发送（零拷贝）
    if let Some(sender) = self.gateway_senders.get(&gateway_id) {
        sender.send(notification.clone())?;  // Arc clone
    }

    Ok(())
}
}

🎯 最佳实践

1. 内部消息传递

推荐：直接传递 Arc<Notification> 或 Notification（通过 mpsc）

#![allow(unused)]
fn main() {
// ✅ 推荐：直接传递（Broker → Gateway）
let (tx, rx) = mpsc::unbounded_channel();
tx.send(notification)?;  // 无需序列化
}

性能：

• 延迟：< 1 μs
• 内存：0（Arc clone）

2. 跨进程通信（未来）

推荐：使用 rkyv 序列化 + iceoryx2 共享内存

#![allow(unused)]
fn main() {
// ✅ 推荐：rkyv + iceoryx2（跨进程）
let bytes = notification.to_rkyv_bytes()?;
shared_memory.write(&bytes)?;

// 接收端：零拷贝反序列化
let archived = Notification::from_rkyv_bytes(shared_memory.read())?;
}

性能：

• 延迟：< 10 μs（包含跨进程通信）
• 内存：0（零拷贝反序列化）

3. WebSocket 边界

推荐：手动构造 JSON（避免 serde Arc 问题）

#![allow(unused)]
fn main() {
// src/notification/gateway.rs

async fn push_notification(&self, notification: &Notification) {
    // ✅ 手动构造 JSON
    let json = notification.to_json();
    session.sender.send(json)?;
}
}

实现：

#![allow(unused)]
fn main() {
// src/notification/message.rs

impl Notification {
    pub fn to_json(&self) -> String {
        format!(
            r#"{{"message_id":"{}","user_id":"{}","priority":{}}}"#,
            self.message_id.as_ref(),
            self.user_id.as_ref(),
            self.priority
        )
    }
}
}

⚠️ 注意事项

1. rkyv 不支持 &'static str

问题：

#![allow(unused)]
fn main() {
// ❌ 编译错误
#[derive(Archive)]
pub struct Notification {
    pub source: &'static str,  // error: &'static str 不实现 Archive
}
}

解决方案：

#![allow(unused)]
fn main() {
// ✅ 使用 String
#[derive(Archive)]
pub struct Notification {
    pub source: String,  // rkyv 支持 String
}
}

2. 字段访问需使用 from_archived!

问题：

#![allow(unused)]
fn main() {
// ❌ 错误：直接访问归档字段可能导致数值错误
assert_eq!(archived.timestamp, 1728123456789);  // 可能不相等！
}

解决方案：

#![allow(unused)]
fn main() {
// ✅ 使用 from_archived! 宏
assert_eq!(rkyv::from_archived!(archived.timestamp), 1728123456789);

// ✅ Arc<str> 可以直接访问
assert_eq!(archived.user_id.as_ref(), "user_01");
}

3. WebSocket 必须使用 JSON

原因：

• Web 客户端无法解析 rkyv 二进制格式
• JavaScript 生态系统基于 JSON
• 调试和监控需要人类可读格式

方案：

#![allow(unused)]
fn main() {
// ❌ 错误：直接发送 rkyv 字节流
let bytes = notification.to_rkyv_bytes()?;
websocket.send(bytes)?;  // Web 客户端无法解析

// ✅ 正确：转换为 JSON
let json = notification.to_json();
websocket.send(json)?;
}

📚 参考资源

• rkyv 官方文档
• rkyv GitHub
• 性能 benchmark
• Zero-copy deserialization 原理

✅ 总结

核心优势：

• 🚀 零拷贝：反序列化无内存分配
• 🚀 零成本：抽象层无运行时开销
• 🚀 写时复制：Arc 共享避免深拷贝
• 🚀 线程安全：Send + Sync 保证并发安全
• 🚀 高性能：反序列化快 25 倍以上