pub struct SystemState { /* private fields */ }Expand description
A heterogeneous collection of payloads describing one system time point.
Fields are declared by a JSON-derived SystemStateSchema. Values are addressed
by those field names but stored in compact optional slots. The type-erased
representation remains private; callers always insert, borrow, mutate, and
extract concrete Rust types. An owned state is Send but not Sync; shared
cross-thread ownership requires an external synchronization boundary.
Implementations§
Source§impl SystemState
impl SystemState
Sourcepub fn advance_time(
&mut self,
physical_time_increment: Option<f64>,
) -> Result<StateTime, StateError>
pub fn advance_time( &mut self, physical_time_increment: Option<f64>, ) -> Result<StateTime, StateError>
Advances the iteration by one after one completed execution-unit step.
Passing None increments only the authoritative iteration and
preserves the current optional physical coordinate. Passing
Some(delta) additionally requires an existing physical coordinate,
a finite delta, and a finite sum. Negative and zero finite deltas are
valid because iteration—not physical time—defines record ordering.
On success, the new StateTime is stored and returned. All validation
occurs before assignment, so every error leaves the original time point
unchanged.
§Errors
Returns:
StateError::IterationOverflowwhen the current iteration isu64::MAX;StateError::MissingPhysicalTimewhen a delta is supplied but the current state has no physical coordinate;StateError::InvalidPhysicalAdvancewhen the delta or resulting coordinate is not finite.
Sourcepub const fn schema(&self) -> &SystemStateSchema
pub const fn schema(&self) -> &SystemStateSchema
Returns the shared immutable field specification.
Sourcepub fn contains_payload(&self, key: &str) -> Result<bool, StateError>
pub fn contains_payload(&self, key: &str) -> Result<bool, StateError>
Reports whether a declared field currently contains a payload.
§Errors
Returns StateError::UnknownField when key was not declared by the
JSON template.
Sourcepub fn initialize_payload<T>(
&mut self,
key: &str,
payload: T,
) -> Result<(), PayloadInsertError<T>>
pub fn initialize_payload<T>( &mut self, key: &str, payload: T, ) -> Result<(), PayloadInsertError<T>>
Initializes one declared field and establishes its concrete Rust type.
This is the assembly-oriented operation: it succeeds exactly once per
field and never silently replaces a value. Every failure preserves the
unchanged incoming payload in PayloadInsertError.
Sourcepub fn insert_payload<T>(
&mut self,
key: &str,
payload: T,
) -> Result<Option<T>, PayloadInsertError<T>>
pub fn insert_payload<T>( &mut self, key: &str, payload: T, ) -> Result<Option<T>, PayloadInsertError<T>>
Sets or replaces a payload while preserving ownership on every outcome.
payload moves into this operation and is never cloned:
- a never-populated declared slot binds itself to
T, receives the payload, and returnsOk(None); - a slot bound to exactly
Treceives it and returns the displaced payload asOk(Some(previous)), orOk(None)when currently empty; - an undeclared key returns
Err(PayloadInsertError<T>)containing the unchanged incoming payload; - a slot bound to another concrete type remains unchanged and returns
the incoming payload in
PayloadInsertError<T>, even when its payload is empty.
Returning a previous payload is deliberate assignment behavior. A caller that does not need that owner should discard it explicitly:
let mut state = spec.create_empty_state(StateTime::from_iteration(0));
drop(state.insert_payload("population", vec![1_u64, 2, 3])?);Type-contract validation occurs before the slot is changed.
Consequently, rejection cannot discard or temporarily remove an
existing scientific value, and take or clear cannot reopen a field
for a different type.
§Errors
Returns PayloadInsertError containing:
StateError::UnknownFieldwhenkeyis undeclared;StateError::TypeMismatchwhen the slot is bound to a different concrete Rust type.
In both cases PayloadInsertError::into_parts recovers the unchanged incoming
T without cloning it.
Sourcepub fn payload<T>(&self, key: &str) -> Result<&T, StateError>where
T: Any,
pub fn payload<T>(&self, key: &str) -> Result<&T, StateError>where
T: Any,
Borrows a populated field as the exact Rust type T.
§Errors
Returns StateError::UnknownField for an undeclared key,
StateError::MissingPayload for an empty slot, or
StateError::TypeMismatch when the stored concrete type differs from
T.
Sourcepub fn payload_mut<T>(&mut self, key: &str) -> Result<&mut T, StateError>where
T: Any,
pub fn payload_mut<T>(&mut self, key: &str) -> Result<&mut T, StateError>where
T: Any,
Mutably borrows a populated field as the exact Rust type T.
Mutation occurs in place and does not clone the payload.
§Errors
Returns StateError::UnknownField for an undeclared key,
StateError::MissingPayload for an empty slot, or
StateError::TypeMismatch when the stored concrete type differs from
T.
Sourcepub fn borrow_payloads<'state, Q>(
&'state self,
keys: Q::Keys<'_>,
) -> Result<Q::Refs<'state>, StateError>where
Q: PayloadTuple,
pub fn borrow_payloads<'state, Q>(
&'state self,
keys: Q::Keys<'_>,
) -> Result<Q::Refs<'state>, StateError>where
Q: PayloadTuple,
Borrows several distinct populated fields as concrete immutable types.
Q is a tuple of expected payload types, while keys is the equally
sized tuple of field names. Tuple positions correspond exactly. The
supported arities are two through eight; single-field callers should use
SystemState::payload. The sealed tuple implementation is internal and
requires no user-defined selector, query object, or macro invocation.
§Errors
Validation first resolves field names and rejects repeated fields, then
checks retained types and payload presence in tuple order. Every check
completes before references are returned. The method reports an unknown
field, repeated field, retained type mismatch, or missing payload through
StateError. An error leaves every slot unchanged.
Sourcepub fn borrow_payloads_mut<'state, Q>(
&'state mut self,
keys: Q::Keys<'_>,
) -> Result<Q::RefsMut<'state>, StateError>where
Q: PayloadTuple,
pub fn borrow_payloads_mut<'state, Q>(
&'state mut self,
keys: Q::Keys<'_>,
) -> Result<Q::RefsMut<'state>, StateError>where
Q: PayloadTuple,
Borrows several distinct populated fields as concrete mutable types.
Q is a tuple of expected payload types, while keys is the equally
sized tuple of field names. All names, duplicate indices, retained type
contracts, and payload presence are validated before any mutable
reference is produced. Payloads remain owned by this state and are not
cloned, moved, serialized, locked, or temporarily removed.
One call should normally surround a complete coupled kernel or sweep so
name lookup and dynamic type validation occur once outside its inner
loop. Supported arities are two through eight; single-field callers
should use SystemState::payload_mut.
§Errors
Returns the same deterministic validation errors as
SystemState::borrow_payloads. A failure leaves the state unchanged and grants
no partial borrow.
Sourcepub fn take_payload<T>(&mut self, key: &str) -> Result<T, StateError>
pub fn take_payload<T>(&mut self, key: &str) -> Result<T, StateError>
Removes and returns the payload from a declared field.
A successful call moves the original concrete T out of its internal
box and leaves the field slot empty while retaining its type contract.
It does not invoke Clone. Type and presence validation occurs before
the payload owner is removed.
§Errors
Returns StateError::UnknownField for an undeclared key,
StateError::MissingPayload for an empty slot, or
StateError::TypeMismatch when the stored concrete type differs from
T.
Source§impl SystemState
impl SystemState
Sourcepub fn clone_structure_without_payloads(&self, time: StateTime) -> SystemState
pub fn clone_structure_without_payloads(&self, time: StateTime) -> SystemState
Creates an empty state sharing schema and retained payload type contracts.
Sourcepub fn replace_time(&mut self, time: StateTime) -> StateTime
pub fn replace_time(&mut self, time: StateTime) -> StateTime
Replaces the complete temporal coordinate and returns the previous one.
Sourcepub fn populated_field_count(&self) -> usize
pub fn populated_field_count(&self) -> usize
Returns the number of fields that currently contain payloads.
Sourcepub fn payload_has_type<T: Any>(&self, key: &str) -> Result<bool, StateError>
pub fn payload_has_type<T: Any>(&self, key: &str) -> Result<bool, StateError>
Reports whether a populated field contains exactly T.
Sourcepub fn clear_payload(&mut self, key: &str) -> Result<bool, StateError>
pub fn clear_payload(&mut self, key: &str) -> Result<bool, StateError>
Drops one payload while retaining its field type contract.
Sourcepub fn clear_all_payloads(&mut self)
pub fn clear_all_payloads(&mut self)
Drops all payloads while retaining schema, time, and type contracts.
Trait Implementations§
Source§impl Clone for SystemState
impl Clone for SystemState
Source§fn clone(&self) -> Self
fn clone(&self) -> Self
Shares the schema and invokes each populated payload’s Clone.
Payload-defined cloning may copy or share backing storage. This method does not guarantee independent mutable scientific values.
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read moreAuto Trait Implementations§
impl !RefUnwindSafe for SystemState
impl !Sync for SystemState
impl !UnwindSafe for SystemState
impl Freeze for SystemState
impl Send for SystemState
impl Unpin for SystemState
impl UnsafeUnpin for SystemState
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more