Skip to content

Initialization model

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 out

The 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.

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.

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.

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.

#[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.