Initialization model
The lifecycle
Section titled “The lifecycle”An initializer is a value implementing Init<T, E, Mode>. It consumes a one-use InitSlot<T, Mode> and returns either an error E or an InitReceipt<T, Mode>:
uninitialized storage → InitSlot → initializer → InitReceipt → drop or move outThe slot carries an exclusive borrow of the storage. slot.write(value) writes one complete T at that address and creates its receipt. The receipt keeps the exclusive borrow for as long as the initialized value is alive, so safe code cannot reuse the same storage while the receipt is still held.
Dropping the receipt drops the value in place. In movable mode, into_inner() reads the value out and suppresses the receipt’s drop. In pinned mode, the receipt cannot move the value out; use as_pin_ref() or as_pin_mut() to obtain pinned borrows.
Why initialize fields separately?
Section titled “Why initialize fields separately?”For a struct, init! uses the InitField metadata generated by #[derive(Init)] to find each field’s address inside the destination. It initializes fields directly there and keeps a receipt for each completed field until every field succeeds. On an ordinary error or panic, those field receipts drop, while the parent slot is never marked initialized. After all fields succeed, the field receipts are forgotten because the complete parent value now owns those fields and will drop them as a whole.
This field-by-field path avoids constructing a complete temporary struct. It is useful for large values and is essential when a pinned field must be initialized at the final address.
Movable and pinned modes
Section titled “Movable and pinned modes”InitMode means the completed value may be moved. PinInitMode means its address must remain stable after initialization. The mode is part of the Init trait and the slot/receipt types, so a movable initializer cannot accidentally satisfy a pinned field’s initializer bound.
The modes also shape access:
| Mode | Initialize | Access after success | Move out |
|---|---|---|---|
InitMode |
init_in or InitStorage |
&T and &mut T through the receipt |
Yes, with into_inner() |
PinInitMode |
pin_init_local!, pin_init_in, or a pinned owner |
Pin<&T> / Pin<&mut T> from the receipt |
No |
pin_init_in is unsafe because the caller must keep the backing storage pinned even if the receipt is forgotten. pin_init_local! packages a local MaybeUninit<T> and its receipt together so the receipt drops before its storage. With alloc, .pin_box() provides an owning pinned allocation.
Error and panic behavior
Section titled “Error and panic behavior”The generated struct initializer runs fields in the order written in the macro invocation. If a later initializer returns an error, receipts for earlier fields clean up those values. The initializer’s error is then returned unchanged unless you use map_err or the macro’s explicit ? ErrorType form to convert it.
Init is an unsafe trait: custom implementations must return a receipt only for a fully initialized target and clean all initialized state on error or panic. Implementing InitDefault or InitRaw has additional unsafe obligations; see errors and safety.
Type-level field metadata
Section titled “Type-level field metadata”#[derive(Init)] provides InitFields metadata and one InitField<KEY> implementation per field. Keys are stable FNV-1a hashes of canonical field names; tuple fields use their decimal indices. The macro checks the full field inventory at compile time, including duplicates and whether every #[pin] field uses pinned, in-place syntax. Do not hand-write these hidden traits for application types.