Skip to content

Runtime API

API Purpose
Init<T, E = Infallible, Mode = InitMode> Unsafe trait. Consumes an InitSlot and returns either a receipt or an error; implementations own the success, rollback, and address-mode guarantees. map_err wraps an initializer and maps only its error.
InitSlot<'slot, T, Mode> One-use capability for an exclusive, uninitialized target. write(value) writes a complete value and returns its receipt.
InitReceipt<'slot, T, Mode> Keeps the target borrowed and owns its destruction. Dropping it drops the target.
InitMode Movable initialization mode. InitReceipt::into_inner is available in this mode.
PinInitMode Pinned initialization mode. The receipt exposes as_pin_ref and as_pin_mut, but cannot move the value out.
InitDefault<T, Mode> Unsafe capability for constructing a default directly in a target slot.
InitDefaultInit<T, Provider> Adapts an InitDefault provider to Init<T, Infallible, Mode>.
InitDefaultValue<T> Uses T::default() by value as a movable-mode default provider.
InitFn<T, E, F> Safely adapts a no-argument FnOnce() -> Result<T, E> closure in movable mode; the returned value is written into the target slot.
InitFnRaw<T, E, F, Mode> Wraps a higher-ranked closure that takes an InitSlot and returns the corresponding receipt or error. InitFnRaw::new is unsafe because the closure must uphold Init’s contract.
InitRaw<T, E, Mode> / RawInit<I> Unsafe raw-pointer initialization contract and its adapter to Init.

InitReceipt implements Deref<Target = T> in either mode. Only movable receipts implement DerefMut; pinned receipts offer pinned borrows instead. Every receipt’s lifetime is tied to the exclusive borrow used to make its slot.

pub fn init_in<'slot, T, I, E>(
slot: &'slot mut MaybeUninit<T>,
initializer: I,
) -> Result<InitReceipt<'slot, T, InitMode>, E>
where
I: Init<T, E>;

init_in is safe because the exclusive &mut MaybeUninit<T> borrow provides the target storage guarantee, while the unsafe Init implementation guarantees that errors and panics leave the slot uninitialized.

pub unsafe fn pin_init_in<'slot, T, I, E>(
slot: Pin<&'slot mut MaybeUninit<T>>,
initializer: I,
) -> Result<InitReceipt<'slot, T, PinInitMode>, E>
where
I: Init<T, E, PinInitMode>;

pin_init_in is unsafe. The caller must preserve the target address until the receipt is dropped. If the receipt is forgotten, the storage must remain pinned and must not be reused.

InitStorage<T>::uninit() creates owned uninitialized storage. .initialize(initializer) consumes it and returns Result<InitValue<T>, E>. .initialize_default() uses T as its InitDefault provider; .initialize_default_with::<Provider>() selects a separate provider. InitValue<T> owns an initialized movable value and provides get, get_mut, into_inner, and deref access.

With the alloc feature:

  • InitBoxExt<T, E>::init_box() initializes a movable Box<T>.
  • PinInitBoxExt<T, E>::pin_box() initializes a Pin<Box<T>> at its allocation’s final address.

Both extension traits are blanket-implemented for initializer types matching their mode bounds.

InitFields, InitField<KEY>, InitFieldInit, InitState, Set, Unset, MovableField, and PinnedField support generated macros and builders. Their methods and fields are hidden implementation details. Application code should use #[derive(Init)], builder methods, and the public initializer entry points instead of implementing the metadata traits manually.

InitFieldInit and InitState are unsafe traits because generated Init implementations rely on their rollback guarantees.

The scalar initializer types InitTyBool, InitTyChar, InitTyI8 through InitTyI128, InitTyIsize, InitTyU8 through InitTyU128, and InitTyUsize are const-generic providers. For example, InitTyU32::<42> initializes a u32 to 42 in either address mode.

Cargo feature Adds
default (empty) Core no-allocation API and defaults for core types
alloc Allocation-backed default providers and init_box / pin_box
std Enables alloc and adds HashMap / HashSet default providers