Lib.rs

› 编码
#byte-stream #byte #byte-slice #serialization #derive #serde #macro-derive

byteserde

一个通用的序列化/反序列化框架，将字节流映射到/从任意结构类型，重点关注性能

由 softstream-link 提供

8 个版本 (5 个重大更新)

0.6.2 2024年1月14日
0.6.1 2024年1月11日
0.6.0 2023年12月24日
0.5.0 2023年11月13日
0.1.1 2023年5月19日

#787 in 编码

Download history 6/week @ 2024-05-12 31/week @ 2024-05-19 35/week @ 2024-05-26 34/week @ 2024-06-02 21/week @ 2024-06-09 36/week @ 2024-06-16 33/week @ 2024-06-23 8/week @ 2024-06-30 12/week @ 2024-07-07 51/week @ 2024-07-14 32/week @ 2024-07-21

每月下载量 104
在 13 个 crate 中使用 (直接使用 9 个)

自定义许可

66KB
1K SLoC

master

动机

  • 这个产品的动机有两个方面

    • 能够通过简单地使用 derive 宏 注释和属性，将通常从网络中获取的 byte slice &[u8] 映射到 Rust 的 struct 数据模型中，自动生成必要的代码。

    • 当使用现有和广泛可用的协议进行序列化时，这非常方便。例如，一个特定应用的 C-Struct。

    • 成为市场上最快字节流序列化/反序列化工具，适用于对延迟敏感的使用案例。以下基准测试结果显示了使用不同框架序列化/反序列化 参考结构 的性能摘要

      • byteserde - ~15ns 读写
      • bincode - ~15ns 读 / ~100ns 写
      • rmp-serde - ~215ns 读写
      • serde_json - ~600ns 读写 - 由于使用了字符串，速度较慢，这是可以理解的

何时使用和何时避免此框架

使用

  • 如果您正在处理以字节流格式（不匹配广泛使用的标准，例如：bincode，protobuf）传输数据的网络协议，请使用此产品来高效地将您的字节流映射到Rust的struct。

  • 您有一个对延迟敏感的使用场景。请注意，此协议在序列化过程中不添加任何模式信息，因此相当于将结构的内存布局（不填充）直接输出。

  • 适合此框架的协议示例。

避免

  • 如果使用广泛使用的标准序列化或反序列化字节流，请避免使用此框架，而是使用相应的标准来处理字节流。

该项目包含三个特性

[email protected] - byteserde_derive/Cargo.toml

  • 包含生成[email protected]特性的派生宏

    • #[derive(ByteSerializeStack)] - 生成ByteSerializeStack特性

    • #[derive(ByteSerializeHeap)] - 生成ByteSerializeHeap特性

    • #[derive(ByteDeserializeSlice)] - 生成ByteDeserializeSlice特性

    • #[derive(ByteSerializedSizeOf)] - 生成ByteSerializedSizeOf特性 - 此特性提供了一个关联方法byte_size()，它给出一个struct的内存大小（以字节为单位），不包括对齐。但是，它不支持堆分配的类型，例如：向量、字符串或它们的派生类型。

    • #[derive(ByteSerializedLenOf)] - 生成ByteSerializedLenOf 特性 - 此特性提供了一个 instance 方法 byte_len(&self)，该方法返回特定实例的内存大小（不包含对齐）。它专门用来处理 ByteSerializedSizeOf 特性 不支持的类型。

  • 更多示例请参考这里
  • 注意：Union 和 Unit 结构不支持，但将来可能会有所改变。

[email protected] - byteserde/Cargo.toml

  • 亮点

    • ByteSerializerStack<CAP> - 提供了将数据序列化到预分配的 byte array [u8; CAP] 上的超快速序列化器，因此得名，它非常快，但代价是需要指定你将要序列化的最大的 struct 的大小。如果你达到这个预分配字节数组的边界，你的序列化将失败。这个实用程序提供了一个重置功能，它将内部计数器移动到开始处，并允许你多次回收缓冲区。

    • ByteSerializerHeap - 提供了一个足够快的序列化器，它将数据序列化到一个 byte vector Vec<u8> 上，因此得名。这个实用程序在性能上做出了一些牺牲，以换取无需提前知道最大的 struct 大小。

    • ByteDeserializerSlice - 接收一个 byte stream &[u8]，无论堆还是栈分配，并将其转换为 struct。

[email protected] - byteserde_types/Cargo.toml

  • 包含相关的可选 ASCII 字符串类型和宏，当解析字节流时处理固定长度字符串非常有用，更多详情请参考 示例部分。

示例 & 概述

  • 请参考 此文档，以获取大量综合示例和功能概述。

依赖项

~170KB