pub struct State { /* private fields */ }Expand description
The shared graph state: channel name → value, with copy-on-write sharing at channel granularity (R0.7 wave 4).
This is the “untyped typed-dict” of the engine: nodes read the full state snapshot and return partial updates keyed by channel name. Type safety for concrete applications is layered on top via serde (de)serialization of individual channel values.
§Copy-on-write representation
Every channel value sits behind an Arc, and the channel map itself
behind another. Cloning a State — the executor’s per-super-step
snapshot, each node’s private copy, the checkpoint’s copy — is two
refcount bumps, O(1) in the state’s size, where it used to be a deep
clone of every channel. A write (a reducer merge at the barrier, an
engine State::insert) touches only what it must: the map is cloned
shallowly when shared (one refcount bump per channel), and a channel’s
value is cloned only when some other State still shares it —
Arc::make_mut semantics per channel. Unchanged channels stay shared
between the pre- and post-step states and every node’s snapshot, which is
also what delta checkpoints diff against (see
crate::checkpoint::encode_delta): sharing and deltas are the same
structural observation.
The public contract is unchanged and pinned: State::get still returns
Option<&Value>, serde still sees the same JSON object (the custom
impls below serialize exactly like the previous transparent Map, so
checkpoints, the wire, the SDKs, and golden files stay byte-identical),
and reducer semantics are untouched. What changed is representation only.
Implementations§
Source§impl State
impl State
Sourcepub fn from_value(value: Value) -> Result<Self>
pub fn from_value(value: Value) -> Result<Self>
Build a state from any serializable value that is a JSON object.
Sourcepub fn to_value(&self) -> Value
pub fn to_value(&self) -> Value
Serialize the whole state back into a Value::Object.
Sourcepub fn into_map(self) -> Map<String, Value>
pub fn into_map(self) -> Map<String, Value>
Consume the state, returning the underlying map. Channel values that no other state shares are unwrapped without copying; shared ones are cloned (copy-on-write).
Sourcepub fn iter(&self) -> impl Iterator<Item = (&str, &Value)>
pub fn iter(&self) -> impl Iterator<Item = (&str, &Value)>
Iterate over (channel, value) pairs.
Sourcepub fn contains(&self, channel: &str) -> bool
pub fn contains(&self, channel: &str) -> bool
true if the channel exists in the state (regardless of value).
Sourcepub fn insert(&mut self, channel: impl Into<String>, value: Value)
pub fn insert(&mut self, channel: impl Into<String>, value: Value)
Directly set a channel’s value, bypassing reducer semantics.
Intended for engine internals (initial state seeding, checkpoint restore). Nodes should always go through reducers.
Trait Implementations§
Source§impl<'de> Deserialize<'de> for State
Parses any JSON object, as the previous transparent Map did.
impl<'de> Deserialize<'de> for State
Parses any JSON object, as the previous transparent Map did.
Source§fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>
Source§impl Serialize for State
Serializes exactly like the Map<String, Value> this type used to wrap
transparently: a JSON object of channel name → value. Byte-identity with
the pre-W4 wire shape is the contract — checkpoints, goldens, and SDK
payloads must not drift because the interior changed.
impl Serialize for State
Serializes exactly like the Map<String, Value> this type used to wrap
transparently: a JSON object of channel name → value. Byte-identity with
the pre-W4 wire shape is the contract — checkpoints, goldens, and SDK
payloads must not drift because the interior changed.