Layout——显式二进制布局
KernLab.Loom.Layout:[BinaryLayout] 标注 + LayoutKind.Explicit struct,编译期生成 Read/Write/校验/常量——
字节序单一声明、字段对齐显式化、NativeAOT 就绪、运行期零反射。
可运行 sample:
samples/Layout/Header(显式头)、samples/Layout/TailAndArray(尾部/数组)、samples/Layout/Failures。
从零跑通
[BinaryLayout(Features = BinaryLayoutFeatures.StructSize)]
[StructLayout(LayoutKind.Explicit, Size = 20)]
public struct Header
{
[FieldOffset(0)] public uint Magic;
[FieldOffset(4)] public ushort Kind;
[FieldOffset(6)] public ushort Length;
[FieldOffset(16), LayoutTail] public byte[] Payload; // 变长尾部([Len 4B][载荷])
}
var buf = new byte[HeaderCodec.GetWriteSize(header)];
HeaderCodec.Write(buf, header);
var back = HeaderCodec.Read(buf); // 或 TryRead(buf, out h, out consumed)
HeaderCodec.Validate(header); // Valid* 约束校验
显式偏移 + 编译期编解码——与手写 BinaryPrimitives 等价但零反射、AOT 就绪。
声明布局
[BinaryLayout(Endianness = LayoutEndianness.BigEndian)] // 端序单一声明(缺省小端)
[StructLayout(LayoutKind.Explicit, Size = 40)]
public struct Packet
{
[FieldOffset(0)] public uint Magic;
[FieldOffset(4)] public byte Flags;
[FieldOffset(5), LayoutBitField(0, 4)] public Nibble High; // 位域:字节内 [bit, width]
[FieldOffset(8), LayoutString(8, Encoding = LayoutStringEncoding.Ascii)] public string Sig; // 定长字符串
[FieldOffset(16), LayoutTail] public byte[] Body; // 变长尾部
[FieldOffset(24), LayoutArray(CountField = nameof(Count))] public Item[] Items; // 定长记录数组段
}
字段形态:
| 形态 | 标注 | 线面 |
|---|---|---|
| 标量 | [FieldOffset] 基元/enum/bool |
定长,端序跟随声明 |
| 位域 | [LayoutBitField(bit, width)](载体 bool/byte/枚举) |
字节内 LSB-first,RMW 不碰未声明位 |
| 定长字符串 | [LayoutString(8, Encoding = ...)](Ascii/Utf8) |
定长字符区,未满 0 填充 |
| 变长尾部 | [LayoutTail](byte[]/ROM/string) |
头后 [Len 4B][载荷],支持多段 |
| 记录数组 | [LayoutArray(CountField)](元素须 [BinaryLayout] struct) |
头后 count×元素 |
| 判别联合 | [LayoutUnion("Disc", value)] |
重叠字节区,按判别值读写活跃分支 |
| 校验 | [ValidEquals]/[ValidRange]/[ValidHasFlags]/[ValidNonDefault] |
生成 Validate |
生成物(<Struct>Codec)
| API | 用途 |
|---|---|
StructSize / Offset_X / Size_X |
布局常数 |
Write(Span, in T, validate=false) |
编码(容量守卫;validate 强制规范字段) |
Read(ReadOnlySpan) / TryRead(ReadOnlySpan, out T, out consumed) |
解码(tail 结构有 TryRead 返回实际消费长度) |
Validate(in T) |
校验约束 |
Read_X(span) / Write_X(span, v) |
单字段读写(Features.FieldAccessors) |
Create() / Or_X(span, v) / IsEmpty_X(span) |
防御性构造 / 标志位置位 / 空判断(Features) |
GetTotalSize(span) / GetWriteSize(in T) |
tail 结构总长探测 / 写侧精确预算 |
用法要点
// 变长尾部:先预算精确缓冲,再写;读侧 TryRead 给实际消费字节(管道切帧)
var size = PacketCodec.GetWriteSize(pkt);
var buf = new byte[size];
PacketCodec.Write(buf, pkt);
PacketCodec.TryRead(buf, out var back, out var consumed); // consumed = 实际帧长
// 数组段:count 落在声明的整型固定字段上
PacketCodec.WriteItemsArray(buf, items); // 或 TryReadItemsArray
诚实边界:Read 在尾部载荷越界时抛 ArgumentException(非 ORE);TryRead 全程返回 false 不抛。
readonly struct + [LayoutTail] 支持构造调用(尾段实参)。[LayoutArray] 元素须同编译标 [BinaryLayout](KLSG013)。
诊断
KLSG001-013(Size 交叉校验/缺 StructLayout/类型不支持/record struct/重叠/OrFlags·IsEmpty 目标/位域载体与区间/生成失败)+ KLSG014(union 判别字段非法)——全默认 Error。