跳转到内容

初始化模型

初始化器是实现 Init<T, E, Mode> 的值。它会消费一次性的 InitSlot<T, Mode>,然后返回错误 E 或 InitReceipt<T, Mode>:

未初始化存储 → InitSlot → 初始化器 → InitReceipt → 析构或移出

槽位携带对存储的独占借用。slot.write(value) 会在该地址写入一个完整的 T,并创建对应凭证。凭证会在已初始化值存活期间继续独占借用存储,因此安全 Rust 代码无法在凭证仍存在时复用同一存储。

销毁凭证会在原位析构目标值。普通模式下,into_inner() 会读出值并禁止凭证再次析构。固定模式下,凭证不能将值移出;应使用 as_pin_ref() 或 as_pin_mut() 获取固定借用。

对于结构体,init! 使用 #[derive(Init)] 生成的 InitField 元数据,定位目标存储内部各字段的地址。宏直接在这些位置初始化字段,并在所有字段成功之前分别保留已完成字段的凭证。若普通错误或 panic 发生,这些字段凭证会负责清理;父级槽位不会被标记为已初始化。全部字段成功后,字段凭证的析构责任会转交给完整的父值,由父值统一析构。

逐字段构造无需先创建完整的临时结构体。对于大型值这很有用;当固定字段必须在最终地址构造时,这也是必要步骤。

InitMode 表示初始化完成后允许移动值。PinInitMode 表示值的地址必须保持稳定。模式属于 Init trait 及槽位/凭证类型的一部分,因此普通初始化器不能满足固定字段所要求的初始化器类型约束。

模式也决定初始化后的访问方式:

模式 初始化入口 成功后的访问 能否移出
InitMode init_in 或 InitStorage 通过凭证取得 &T 和 &mut T 可以,使用 into_inner()
PinInitMode pin_init_local!、pin_init_in 或固定拥有者 从凭证取得 Pin<&T> / Pin<&mut T> 不可以

pin_init_in 是 unsafe,因为即使凭证被遗忘,调用方仍必须保证后备存储保持固定。pin_init_local! 会将局部 MaybeUninit<T> 与凭证一起管理,保证凭证先于存储析构。启用 alloc 后,.pin_box() 可创建拥有型固定分配。

生成的结构体初始化器按宏调用中书写的顺序初始化字段。如果后续字段返回错误,较早字段的凭证会负责清理这些值。除非使用 map_err 或宏调用中的显式 ? ErrorType 形式转换错误,否则初始化器错误会原样返回。

Init 是 unsafe trait:自定义实现只能在目标完整初始化后返回凭证,并且必须在错误或 panic 时清理所有已构造状态。实现 InitDefault 或 InitRaw 还有额外的 unsafe 义务,详见错误处理与安全。

#[derive(Init)] 会提供 InitFields 元数据,并为每个字段生成一个 InitField<KEY> 实现。字段键是规范字段名的稳定 FNV-1a 哈希;元组字段使用十进制索引。宏会在编译期检查完整字段清单,包括重复字段、遗漏字段,以及每个 #[pin] 字段是否使用固定原位语法。应用类型不应手写这些隐藏 trait。