Crate magicstatemachines 

Ergonomic typestate wrappers for compiler-enforced state machines.

This crate requires nightly Rust for arbitrary_self_types.

MagicStateMachines lets a state-machine contract live separately from the runtime type that implements it. A definition crate owns the stand-in type, state marker ZSTs, initial states, legal transitions, and state unions. An implementation crate connects a runtime type to that contract with StateMachineImpl! and exposes ordinary inherent methods whose receiver type carries the current state.

The core receiver type is State<Storage, T, S>, where T is the runtime implementation, S is the current state marker, and Storage selects how the runtime value is held. Methods usually constrain storage by capability: SRef for read-only access, SMut for mutable transitions, SPinMut for pinned transitions, and SMove when storage must move by value. This allows the same state-machine methods to work for owned values, boxes, pinned boxes, shared guard views, and custom storage backends.

In the default configuration this crate denies unsafe code. The dynZST feature uses the external dynzst crate for thin erased ZST state markers. Without tracing, directly owned state wrappers are layout-transparent over the runtime data, and concrete-state transitions are statically dispatched. When state crosses a boundary the compiler cannot prove, such as shared storage behind Rc, Arc, RefCell, Mutex, or RwLock, the committed erased state is checked at the boundary before returning a typed view.

State unions support methods over a set of states. A union such as Online generates a sealed membership trait such as InOnline, a discriminated state representation, and an enum such as OnlineEnum. Static union transitions use transition! with the const form when all members share the same transition body. Dynamic union transitions use the dyn form when the concrete member must be discriminated first.

Macros

StateMachineDefinition

Defines the state-machine contract for a stand-in type.

StateMachineImpl

Connects a runtime type to a state-machine definition and generates its effects.

StateUnion

Defines a named union of concrete state markers.

States

Defines concrete state marker ZSTs.

transition

Performs a transition inside a module that invoked StateMachineImpl!.

Structs

ConcreteStateKind

Marker kind for concrete state ZSTs.

ConcreteStated

Raw runtime data paired with a concrete state marker.

DynState

Direct erased-state storage without a runtime borrow checker.

DynStorage

Storage marker used by DynState views.

MutexStorage

SharedStorage implementation backed by Mutex.

RefCellStorage

SharedStorage implementation backed by RefCell.

RwLockStorage

SharedStorage implementation backed by RwLock.

SharedState

Shared state using an explicit, replaceable storage backend.

SharedValue

The state marker and runtime data held by a shared-storage backend.

State

A state token parameterized by storage, runtime implementation, and state.

StateMut

Mutable typed view into shared state.

StateOwned

A directly owned runtime implementation T whose compile-time state is S.

StateRef

Immutable shared-state read guard used as State storage.

StorageStateMut

Generic State backend for a mutable shared-state guard.

StorageStateOwned

Backend for directly owned values.

StorageStateOwnedBox

Backend for Box<T> owned values.

StorageStateOwnedPinBox

Backend for Pin<Box<T>> owned values.

StorageStateRef

Generic State backend for an immutable shared-state guard.

UnionStateKind

Marker kind for generated union state markers.

WeakSArc

Weak counterpart to SArc.

WeakSRc

Weak counterpart to SRc.

WrongStateError

Failure caused by asking a shared container for the wrong state marker.

Enums

SharedStateError

Failure to acquire a typed view of shared state.

Traits

EnumExt

Convenience extension for converting a state into a union’s generated enum.

In

Marks a state as being a concrete marker or a member of a generated state union.

Initial

Declares that a definition crate permits TState as an initial state.

MayTransition

Storage backend whose state token may be consumed and retagged by a transition.

SMapRuntime

Storage backend that can transform the runtime value while preserving state.

SMove

Storage backend whose state token can be consumed by value.

SMut

Storage backend that can expose a mutable runtime reference.

SPinMut

Storage backend that can expose a pinned mutable runtime reference.

SPinRef

Storage backend that can expose a pinned runtime reference.

SRef

Storage backend that can expose a runtime reference.

SharedStorage

Replaceable storage backend for super::SharedState.

SharedStorageView

Guard types used by runtime-erased state views.

StateClone

State policy permitting crate::State to clone its runtime value.

StateCopy

State policy permitting crate::State to copy its runtime value.

StateKind

Classifies state marker types.

StateMachineImpl

Connects an implementation type to a state-machine definition.

StateMarker

Common trait implemented by concrete states and generated union markers.

StateStorage

Storage backend used by State.

StateStorageNew

Storage backend that can create initial owned state.

StateTrait

Runtime identity for a state marker after the concrete marker type has been erased.

StateUnionDiscriminant

Selects the value-carrying enum type for a union marker.

Transition

Declares that a definition crate permits TFrom -> TTo.

Functions

pin_mut

Mutably borrows a state’s runtime value through its storage’s pin guarantee.

pin_ref

Borrows a state’s runtime value through its storage’s pin guarantee.

transition

Creates a callable transition requiring the definition’s arguments.

transition_mut

Creates a callable transition for a mutable shared-state guard.

transition_state

Creates a callable transition for generic state storage.

Type Aliases

DiscriminatedState

Union-typed state that still remembers its concrete variant.

RuntimeStateMarker

Runtime marker used when borrowing Marker from shared storage.

SArc

Shared state backed by Arc<Storage::Storage<T>>.

SArcMutex

Shared state backed by Arc<Mutex<...>>.

SArcRwLock

Shared state backed by Arc<RwLock<...>>.

SBox

Owned state whose runtime value is stored in Box<T>.

SMutView

State view held by a mutable guard from a shared storage backend.

SMutex

Mutable-guard storage backend for MutexStorage.

SOwned

Short alias for StorageStateOwned.

SPin

Owned state whose runtime value is pinned by an arbitrary pinning pointer.

SPinBox

Owned state whose runtime value is stored in Pin<Box<T>>.

SRc

Shared state backed by Rc<Storage::Storage<T>>.

SRcRefCell

Shared state backed by Rc<RefCell<...>>.

SRefCell

Mutable-guard storage backend for RefCellStorage.

SRefView

State view held by an immutable guard from a shared storage backend.

SResult

A result whose success and error values are states of the same machine.

SRwLock

Mutable-guard storage backend for RwLockStorage.

WeakSArcMutex

Weak handle for SArcMutex.

WeakSArcRwLock

Weak handle for SArcRwLock.

WeakSRcRefCell

Weak handle for SRcRefCell.