VLink  2.3.0
A high-performance communication middleware
🗜️ 3. 消息序列化

序列化负责消息对象与传输字节之间的双向转换:将一个消息对象编码为可在网络或共享内存中传递的字节流,并在对端还原为同类型对象。在 VLink 中,这一过程由消息类型在编译期决定并由框架自动执行——应用层将合适的消息类型作为模板参数传给 Publisher<T>、Subscriber<T> 等原语,编解码即随通信调用透明完成,无需手写序列化代码,也无需注册编解码器。

本章先建立"按类型推导编码"的机制模型,再给出各类型族的选型判据与最小用法,最后说明边界条件与典型错误。


🧩 3.1 概念与机制

序列化在 VLink 中是一个**编译期决议、运行期执行**的过程,遵循三条不变量:

  • **编码由类型决定** 每个原语以消息类型 T 为模板参数。框架据此在编译期选定唯一的编解码策略,调用方不参与选择,也不在 URL 或运行期配置中指定序列化方式。
  • **编解码内联于通信调用** publish()、listen()、invoke()、set()、get() 在内部完成编码与解码,应用代码不直接调用任何序列化接口。
  • **不支持的类型在编译期失败** 若 T 既非内置可识别类型、又未提供自定义编解码,构造原语时即编译报错(提示形如 <MsgT> is not a supported Serializer type.),不会推迟到运行期。

由此得到一项重要的工程性质:**切换序列化方式等价于更换消息类型,通信代码不变。** 同一段发布/订阅逻辑,将 T 从 POD 结构体换为 Protobuf 消息,即把内存直拷切换为跨语言二进制编码,URL 与调用点均无需改动。

值类型可由 std::shared_ptr<T> 包裹传入,框架自动解包后按 T 推导编码(仅值族探测器解包,指针/builder/字符指针族不解包)。

类型识别在编译期完成:框架按固定优先级依次探测各类型族的特征,**命中第一个即停止**(precedence chain, first-match-wins)。优先级自高至低为 Bytes → DynamicData → SOME/IP → CDR → Protobuf → Protobuf 指针 → FlatBuffers 对象 → FlatBuffers 表指针 → FlatBuffers builder → 自定义 → string → const char* → POD → POD 指针 → 流式兜底,全部未命中则为不支持类型。因此一个类型若同时满足多条特征,将归入更靠前的那一族。


📋 3.2 类型族、编码与选型

下表列出框架可自动识别的常用消息类型族、对应编码、关键约束及其适用场景(另有一种"流式兜底"编码作为末位回退,见 3.7)。选定一种类型传给原语,编码方式即随之确定。

消息类型 自动编码 关键约束 适用场景
POD 结构体(SensorData) 内存直拷 两端结构体定义须完全一致;不跨字节序 同机高频、结构固定、追求极致开销
POD 指针(LargeFrame*) 指针内容视图 避免 serializer 中间 owning 分配;SHM 发布仍复制一次进 transport loan 大消息同机单拷贝传递
FlatBuffers 对象(MyMsgT) FlatBuffers NativeTable Object API,读写均便利 高性能结构化消息、需向前兼容
FlatBuffers 表指针(const MyMsg*) FlatBuffers(零拷贝只读) 指针指向接收缓冲区,仅在回调内有效 高性能只读路径
FlatBuffers builder(含 fbb_ + Finish()) FlatBuffers 直接发布手工构建的 builder,序列化时完成构建并按最终大小申请目标缓冲 自管缓冲区的高性能写入路径
Protobuf 消息(MyMsg) Protobuf 二进制 需由 .proto 生成代码 跨语言、字段随版本演进
Protobuf 指针(MyMsg*) Protobuf 二进制 调用方管理发送指针;框架创建接收或响应对象前须先 bind_proto_arena(),每次投递在 Arena 中分配独立对象 高频收发大量消息
SOME/IP 结构(VLINK_SOMEIP_FIELDS(...)) AUTOSAR SOME/IP payload 宏按声明顺序展开字段;支持嵌套结构、结构体数组、map、union、UTF-16 与 TLV 可选成员,部署边界见 3.5 车载服务 payload、跨大小端结构化消息
DDS IDL 类型(MyMsg) CDR 基础无 key 传输可直接使用;完整类型元数据见 3.6 与外部 DDS 系统互操作
vlink::Bytes 原始字节直传 框架不解释其结构 透明代理、私有二进制协议、原始帧
std::string / const char* 文本直传 std::string 支持收发;const char* / char[] 仅支持发送 日志、命令字符串
自定义类型(重载 operator>>/<<) 用户编解码 字段顺序须严格对应,见 3.5 自有紧凑布局、带外信息
vlink::DynamicData 类型名标签 + 已序列化负载 运行期按类型名标签选择编解码,无需编译期固定消息类型,见 3.6 监控、协议桥接

判据的取舍要点:POD 提供最低开销,但不携带版本信息且不跨字节序;FlatBuffers 与 Protobuf 以编码开销换取结构演进能力;Bytes 不解释内容,适合协议透传。后端选择与 URL 写法见 传输后端;面向感知的零拷贝容器见 零拷贝。

发送字符指针时,调用方必须保证其可访问到 NUL;字符数组必须在数组边界内包含 NUL。两者都只序列化首个 NUL 之前的字节。接收端不能使用 char* 或 const char*,因为指针本身不拥有反序列化存储;接收文本必须使用 std::string。

传输后端集成可调用公开的 Serializer::serialize_to_transport<TypeT>():use_loan=true 且存在非零 size hint 时,回调至多按序列化大小请求一次目标 Bytes,返回值既可以是真实 loan,也可以是 owning storage;返回值必须与 hint 大小完全相同,codec 不得替换 transport loan。size hint 为 0 时不请求 loan,直接回退到 owning 序列化。普通应用仍应使用 Publisher、Client、Server 或 Setter,由框架自动选择该路径。builder 类型在进入该路径后会完成构建,即使目标分配失败也应使用新 builder 重试。


🔧 3.3 Protobuf

定义 .proto 并生成 C++ 代码后,将消息类型直接传给原语即可(CMake 集成见 快速开始)。

#include "vlink/vlink.h"
#include "my_message.pb.h"
vlink::Publisher<example::VehicleState> pub("dds://vehicle/state");
example::VehicleState state;
state.set_speed(80.0f);
state.set_gear(3);
pub.publish(state);
vlink::Subscriber<example::VehicleState> sub("dds://vehicle/state");
sub.listen([](const example::VehicleState& s) {
VLOG_I("speed=", s.speed(), " gear=", s.gear());
});
#define VLOG_I(...)
Definition: logger.h:900

高频发布大量消息时,可用 MyMsg* 配合 Arena 分配,避免反复构造与析构带来的内存管理开销:

google::protobuf::Arena arena;
vlink::Publisher<example::VehicleState*> pub("dds://vehicle/state");
auto* state = google::protobuf::Arena::Create<example::VehicleState>(&arena);
state->set_speed(80.0f);
pub.publish(state);

框架需要创建裸 Protobuf 指针对象时必须先调用 bind_proto_arena():这包括 Subscriber 的 MsgT、Server 的 ReqT / RespT、Client 的 RespT 和 Getter 的 ValueT。Subscriber / Server 应在 listen() 前绑定,Client 应在首次调用前绑定;Getter 建议以 InitType::kWithoutInit 构造,绑定后再 init()。框架会为每次投递创建独立消息,避免嵌套或并发回调覆盖同一对象;消息占用的存储会保留到调用方 reset 或销毁 Arena。完整节点说明见 通信模型。


📦 3.4 FlatBuffers 与 POD

🧱 3.4.1 FlatBuffers

FlatBuffers 提供两种访问路径:以 Object API(MyMsgT)读写,或以表指针(const MyMsg*)零拷贝只读。CMake 集成同见 快速开始。

#include "vlink/vlink.h"
#include "my_message_generated.h"
vlink::Publisher<example::VehicleStateT> pub("shm://vehicle/state");
example::VehicleStateT state;
state.speed = 80.0f;
state.gear = 3;
pub.publish(state);
vlink::Subscriber<example::VehicleStateT> sub("shm://vehicle/state");
sub.listen([](const example::VehicleStateT& s) {
VLOG_I("speed=", s.speed);
});

订阅端以 const MyMsg* 直接读取接收缓冲区,跳过反序列化,是 FlatBuffers 路径中开销最低的读法:

sub.listen([](const example::VehicleState* s) {
if (s != nullptr) {
VLOG_I("speed=", s->speed());
}
});

边界条件:表指针指向接收缓冲区,仅在回调内有效;需在回调外保留时,应先 s->UnPack() 拷成 Object(MyMsgT)再保存。

⚙️ 3.4.2 POD 结构体与原始字节

满足 trivial 且 standard-layout 的 C 风格结构体按 sizeof 内存直拷,是除零拷贝外开销最低的编码方式。

struct SensorData {
float temperature;
float humidity;
uint64_t timestamp_us;
};
vlink::Publisher<SensorData> pub("shm://sensor/imu");
pub.publish(SensorData{25.6f, 60.2f, now_us()});
vlink::Subscriber<SensorData> sub("shm://sensor/imu");
sub.listen([](const SensorData& d) {
process(d.temperature, d.humidity);
});

边界条件:POD 不携带任何版本或结构元信息,发布端与订阅端的字段顺序与大小必须完全一致,且不做字节序转换,因此不适用于跨架构(大小端不同)通信。MyStruct* 可避免 serializer 的中间 owning 分配,但普通 SHM 发布仍会把数据复制进 transport loan;发布端真正就地写池内存须使用 Publisher<Bytes>::loan()。

vlink::Bytes 原样传输字节内容,框架不解释其结构,适合透明代理与私有协议:

vlink::Publisher<vlink::Bytes> pub("shm://raw/channel");
auto buf = vlink::Bytes::create(256);
std::memcpy(buf.data(), payload, 256);
pub.publish(buf);
vlink::Subscriber<vlink::Bytes> sub("shm://raw/channel");
sub.listen([](const vlink::Bytes& msg) {
process_raw(msg.data(), msg.size());
});

Bytes 的完整工厂、压缩、Base64、CRC 等工具方法见 基础库。


🧬 3.5 SOME/IP 与自定义序列化器

🚗 3.5.1 SOME/IP payload

在结构体内用 VLINK_SOMEIP_FIELDS(...) 按线格式顺序列出字段,框架即将该类型推导为 Serializer::kSomeipType。宏同时生成精确大小查询、带显式 offset 参数的 serialize()、读取 vlink::Bytes payload 区域的 deserialize() 成员,以及面向 vlink::Bytes 的 operator>> 编码和 operator<< 解码方法,不需要逐字段手写编解码:

#include "vlink/vlink.h"
#include <array>
#include <cstdint>
#include <string>
#include <vector>
struct SomeipChild {
int16_t delta{0};
std::string label;
VLINK_SOMEIP_FIELDS(delta, label)
};
struct SomeipMessage {
uint8_t state{0};
std::string name;
std::vector<uint16_t> samples;
std::array<uint32_t, 2> limits{};
std::vector<SomeipChild> children;
vlink::Bytes payload;
VLINK_SOMEIP_LENGTH(samples, 4U), VLINK_SOMEIP_LENGTH(limits, 0U),
children, payload)
};
static_assert(vlink::Serializer::get_type_of<SomeipMessage>() == vlink::Serializer::kSomeipType);
Compile-time codec detection and dispatch for VLink message payloads.
SOME/IP payload codec helpers and template field traversal.
#define VLINK_SOMEIP_STRUCT_LENGTH(width)
Selects the structure length field width: 0 (default, omitted), 1, 2, or 4 bytes; TLV structures must...
Definition: someip_serializer.h:2308
#define VLINK_SOMEIP_FIELDS(...)
Declares a structure as a SOME/IP payload and lists its fields in wire-format order.
Definition: someip_serializer.h:2517
#define VLINK_SOMEIP_ALIGNMENT(alignment)
Macro Definitions.
Definition: someip_serializer.h:2280
#define VLINK_SOMEIP_LENGTH(field, width)
Wraps one UTF-8/UTF-16 string, Bytes, vector, or map field with a 1, 2, or 4-byte length width; a fix...
Definition: someip_serializer.h:2317
#define VLINK_SOMEIP_ENDIAN_LITTLE
Selects little-endian SOME/IP payload scalar values.
Definition: someip_serializer.h:2301

支持标量、无符号定宽枚举、UTF-8/UTF-16 字符串、vlink::Bytes、vector、array、map、variant、 宏声明的嵌套结构和多维容器;std::optional 仅用于 TLV 成员。

AUTOSAR R25-11 部署规则如下:

  • payload 标量默认大端,可用 VLINK_SOMEIP_ENDIAN_* 配置;长度、TLV tag 和 union 选择符始终为网络字节序。
  • 字符串、容器和 union 长度默认 4 字节,结构体默认无长度;字符串、Bytes、动态容器和 union 可配置 1/2/4 字节宽度,结构体及固定 array 维度还可用 0 省略长度。
  • alignment 默认 1,可用 VLINK_SOMEIP_ALIGNMENT 配置为 1/2/4/8/16/32;仅在后续仍有字段时为可变字段补齐 padding,并按含 16 字节头的普通 SOME/IP 消息起点计算。
  • UTF-8/UTF-16 长度包含 BOM、内容和终止符;动态字符串输入已有 BOM 时不会重复添加,定长字符串用固定 wire size 补零,UTF-16 默认 BE,奇数长度忽略最后一字节。map 条目紧邻编码并拒绝重复 key;variant 选择符从 1 开始,首项显式使用 std::monostate 时以选择符 0 表示 NULL,未知选择符会被拒绝。

TLV 结构的每个字段都必须使用 VLINK_SOMEIP_TLV*,data ID 在结构内唯一且不超过 12 位,并声明非零 VLINK_SOMEIP_STRUCT_LENGTH 和 1 字节 alignment。定宽字段使用 wire type 0–3;复杂字段动态选择 wire type 5–7,VLINK_SOMEIP_TLV_STATIC_LENGTH 使用 wire type 4。未知 data ID 可跳过,重复的已知 ID 或缺失的必选字段 会被拒绝;缺失的 optional 字段会重置。TLV 下级长度必须与顶层宽度一致,多维数组使用对应的 TLV array 宏; AUTOSAR 工具会继承该配置,无法表达的组合会明确拒绝。

不支持字段级混合/opaque 端序、字段级 alignment 和 bit-field;TLV union 仅支持默认 4 字节 selector,省略 length 的 union 当前仅支持等宽标量或枚举 alternatives。生成器会为直接字段的数组、Bytes 和字符串上限生成注释及 maximum field wrapper。字符串超过最大 Unicode 字符数时拒绝输入;动态 vector/Bytes 只保留前 N 项/字节,并按长度边界 跳过余量。生成的 check_available() 仍在序列化前校验容器大小。多维容器 maximum 暂不表达。payload 上限为 UINT32_MAX - 8;失败可能保留已解码字段,输入输出缓冲不得与对象存储重叠。该 codec 只处理 payload, 不包含 16 字节 SOME/IP 消息头,也不绑定 someip:// 传输;Python 仅收发已编码的 vlink.Bytes。non-TLV 只能在顶层末尾或结构长度边界内忽略未知尾部,不能跳过插入或乱序字段。 这些是 payload codec 能力,不代表 AUTOSAR 工具支持全部 CP 类型模型;工具的明确边界见其 README。

🧱 3.5.2 自定义编解码

为任意类型重载下列两个运算符,框架即自动用其编解码,无需注册:

void operator>>(vlink::Bytes& out) const; // 将自身写入 out(编码)
void operator<<(const vlink::Bytes& in); // 从 in 还原自身(解码)

运算符也可返回 bool 表示成败(返回 false 即上报编解码失败)。

当消息既非内置可识别类型,又需要自有的紧凑布局或带外信息时,自定义序列化器是接入私有协议的标准途径:

#include "vlink/vlink.h"
#include <cstring>
#include <limits>
struct MyCustomProtocol {
uint16_t cmd{0};
std::vector<uint8_t> payload;
bool operator>>(vlink::Bytes& out) const {
if (payload.size() > std::numeric_limits<uint32_t>::max()) {
return false;
}
uint32_t n = static_cast<uint32_t>(payload.size());
out = vlink::Bytes::create(sizeof(cmd) + sizeof(n) + payload.size());
if (out.empty()) {
return false;
}
uint8_t* p = out.data();
std::memcpy(p, &cmd, sizeof(cmd)); p += sizeof(cmd);
std::memcpy(p, &n, sizeof(n)); p += sizeof(n);
if (!payload.empty()) {
std::memcpy(p, payload.data(), payload.size());
}
return true;
}
bool operator<<(const vlink::Bytes& in) {
constexpr size_t kHeaderSize = sizeof(cmd) + sizeof(uint32_t);
if (in.size() < kHeaderSize || in.data() == nullptr) {
return false;
}
const uint8_t* p = in.data();
std::memcpy(&cmd, p, sizeof(cmd)); p += sizeof(cmd);
uint32_t n = 0;
std::memcpy(&n, p, sizeof(n)); p += sizeof(n);
if (static_cast<size_t>(n) != in.size() - kHeaderSize) {
return false;
}
payload.assign(p, p + n);
return true;
}
};
vlink::Publisher<MyCustomProtocol> pub("dds://custom/channel");
MyCustomProtocol msg;
msg.cmd = 0x01;
msg.payload = {0xAA, 0xBB, 0xCC};
pub.publish(msg);

实现约束:

  • operator>> 内先计算所需字节数,再以 vlink::Bytes::create(size) 分配。
  • operator<< 不得假设 in.size() 固定,读取前需做长度合法性检查。
  • 写入与读取的字段顺序必须严格对应;跨架构通信时显式处理字节序。

🔗 3.6 DDS CDR 与 DynamicData

CDR 是 DDS 标准二进制格式,用于与外部 DDS 系统互操作,消息类型通常由 IDL 自动生成。基础无 key CDR 传输不强制注册 TypeSupport;需要 key、TypeIdentifier/TypeObject 或原生最大序列化尺寸时,应在端点初始化前注册:

DDS target 向消费者导出 VLINK_SUPPORT_CDR;Serializer 包含 Fast-CDR 成功后定义 VLINK_HAS_CDR,后续 CDR 实现仅判断该能力宏。显式定义 VLINK_SUPPORT_ROS2 会同时请求 CDR 支持;ROS2 Fast RTPS 类型支持头包含成功后定义 VLINK_HAS_ROS2,无需再单独定义 VLINK_SUPPORT_CDR。请求的依赖不可用时编译器给出警告且不定义对应 VLINK_HAS_*。Typed Serializer 生成 XCDRv1;Bytes 路径可原样承载 XCDRv1/XCDRv2,FastDDS 3 发送时会校验 payload encapsulation 与 DataWriter representation QoS 一致,不进行隐式转码。

DDS raw/CDR 模式与 CDR 类型名参与原生 endpoint 创建,必须在 init() 前确定;需要修改时先 deinit(),重新设置后再 init()。仅变更其他序列化元数据不受此限制。

#include "MyMessage.h"
#include "MyMessagePubSubTypes.h"
vlink::DdsConf::register_topic<MyMessagePubSubType>("my_topic");
vlink::Publisher<MyMessage> pub("dds://my_topic");
MyMessage msg;
msg.value(42);
pub.publish(msg);

vlink::DynamicData 在运行期承载类型名与已序列化负载,无需在编译期固定消息结构,适用于调试工具、监控与协议桥接。写入用 load(type, value),读取用 as<T>() 或 convert(out);宏声明的 SOME/IP 结构也可装入并按 SchemaType::kRaw 保存 payload:

vlink::Publisher<vlink::DynamicData> pub("dds://dynamic/topic");
msg.load("float", 80.0f);
pub.publish(msg);
vlink::Subscriber<vlink::DynamicData> sub("dds://dynamic/topic");
sub.listen([](const vlink::DynamicData& d) {
VLOG_I("type=", d.get_type(), " value=", d.as<float>());
});
Self-describing serialised payload tagged with an inline type name.

边界条件:类型名连同结尾 \0 须短于 20 字节(load() 在编译期 static_assert 校验);负载类型须为 Serializer 支持的类型族。CDR 与裸/shared_ptr 包装的嵌套 DynamicData 在两个方向都被拒绝; load() 还会拒绝不能预留 20 字节类型名前缀的 FlatBuffers 表指针和 POD 指针。完整字段操作见 include/vlink/extension/dynamic_data.h。


⚠️ 3.7 边界条件与常见错误

含 std::vector 等非平凡成员、又未重载序列化运算符的结构体不会被自动识别,构造原语时编译失败:

struct BadMsg {
int x;
std::vector<int> data;
};
vlink::Publisher<BadMsg> pub("shm://bad"); // 编译失败:<MsgT> is not a supported Serializer type.

修复方式:若字段满足已支持的 SOME/IP 类型,可用 3.5 的 VLINK_SOMEIP_FIELDS(...) 声明;否则改用 Protobuf、FlatBuffers 或手写自定义序列化器。

其余高频边界条件汇总如下:

约束 表现与处置
POD 跨架构字节序 内存直拷不做字节序转换;大小端不同的机器间通信应改用 Protobuf / FlatBuffers / CDR,或在自定义序列化器内显式处理字节序
FlatBuffers 零拷贝指针生命期 const MyMsg* 指向接收缓冲区,回调返回后即失效;需在回调外保留时先 s->UnPack() 拷成 Object
C 字符串方向性 const char* / char[] 只支持序列化;反序列化为字符指针会失败,接收端应声明为 std::string
SOME/IP 部署范围 宏支持 payload 大/小端、1/2/4/8/16/32 字节 alignment、字段/结构体/多维数组的 0/1/2/4 字节长度宽度,以及定长/变长 UTF-8/UTF-16 字符串、map、union 和带 optional 成员的 TLV 结构;bit-field、字段级混合端序/alignment、TLV union 非默认 selector 不能直接使用
自定义序列化器字段对齐 写入与读取的字段顺序必须严格对应,operator<< 读取前须校验 in.size() 合法性
流式回退编码 若类型对 std::stringstream 同时重载了 <</>>(且非上述任一类型族),框架会以文本流作为兜底编码,而非编译失败;需要紧凑二进制时应改用 3.5 的 operator>>/<<(Bytes&)

📚 相关文档