第26.13章:序列化与二进制格式

English

1. 没有独立的序列化框架

fast_io 没有带 schema 注册、反射或运行期类型注册表的序列化框架。 二进制格式用和其他 I/O 一样的三件工具写:标量用操纵器,blob 用字节操作, 记录用长度或分隔符分帧。

重要的部分是显式决定线格式。不要把一个结构体的地址强转成 std::byte* 直接写:padding、对齐和原生端序不是协议的一部分。 每个字段用确定的宽度和字节序写。

2. 端序辅助

条目 含义 模块
byte_swap(value) 反转无符号整数的字节序。 fast_io
little_endian(value) 把原生整数转成小端表示。 fast_io
big_endian(value) 把原生整数转成大端表示。 fast_io
le_put<N>(value) 写一个 N 位小端整数。 头文件侧
be_put<N>(value) 写一个 N 位大端整数。 头文件侧
le_get<N>(ref)、be_get<N>(ref) 按选定字节序读一个 N 位整数。 头文件侧
lebe_put<endian, N>(value) le_put/be_put 背后的通用形式。 头文件侧
iec559_le_put、iec559_be_put IEEE-754 浮点字节序辅助。 头文件侧

auto const wire{::fast_io::big_endian(value)};
::fast_io::operations::write_all_bytes(
    out, reinterpret_cast<::std::byte const *>(&wire), sizeof(wire));

转换函数是 constexpr,并处理宿主原生字节序,包括非小端/非大端目标。 le_put/le_get 家族是格式化器层替代方案: 通过 print/scan 读写,而不是原始字节复制。

3. LEB128

LEB128 是可变长度整数编码。fast_io 以一对操纵器提供它:


::fast_io::io::print(out, ::fast_io::mnp::leb128_put(size));

::std::uint64_t decoded{};
::fast_io::io::scan(in, ::fast_io::mnp::leb128_get(decoded));
条目 方向 模块
leb128_put(value) 写 fast_io
leb128_get(ref) 读 fast_io

编码器处理有符号和无符号整数。解码器检查截断和溢出; 畸形流是解析错误,不是部分值。

4. WebAssembly 编码

WebAssembly 辅助是同一组原语上的头文件侧别名:

条目 编码
wasm_varint_put、wasm_varint_get LEB128 varint。
wasm_uint32_put、wasm_uint32_get 32 位小端。
wasm_uint64_put、wasm_uint64_get 64 位小端。
wasm_float_put、wasm_float_get IEEE-754 小端浮点。

它们不在模块导出列表里。需要时包含 #include <fast_io.h>。

5. 固定大小字节窗口

正好 N 字节的记录用 read_all_bytes / write_all_bytes。已知长度的文本 token 用 str_get_all(ref, n):


::std::byte header[16];
::fast_io::operations::read_all_bytes(in, header, sizeof(header));

::std::byte payload[64];
::fast_io::operations::write_all_bytes(out, payload, sizeof(payload));

这些操作在无法填满整个窗口时失败。短读不会被悄悄当成完整记录; 短写不会被悄悄当成完整消息。

6. 一个分帧二进制记录

长度前缀记录是避免分隔符歧义的最简单格式。长度是 LEB128 varint,body 是原始字节:


void write_record(::fast_io::obuf_file &out,
                  ::fast_io::span<::std::byte const> body)
{
    ::fast_io::io::print(out, ::fast_io::mnp::leb128_put(body.size()));
    ::fast_io::operations::write_all_bytes(out, body.data(), body.size());
}

std::uint64_t length{};
::fast_io::io::scan(in, ::fast_io::mnp::leb128_get(length));

::fast_io::vector<::std::byte> body;
body.resize(length);
::fast_io::operations::read_all_bytes(in, body.data(), body.size());

两条规则让它安全。第一,在分配之前用最大值检查长度。 第二,短 body 是截断记录,要失败;不要处理部分 payload。 同一模式适用于网络帧、文件记录和内存缓冲区。

7. 不要靠强转序列化

union 和 bit-field 细节在 第25.1章。 字节操作在 第26.9章。

8. 模块与头文件边界

fast_io 模块导出 byte_swap、little_endian、 big_endian、leb128_put、leb128_get 以及字节读写操作。le_put/le_get 家族、IEEE-754 辅助、 WebAssembly 辅助和 str_get_all 目前在头文件侧。

要点