Table of Contents

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。

相关

字节序/对齐/黄金快照纪律全文:二进制布局规格;性能基线见规格区。