Skip to main content

SystemState

Struct SystemState 

Source
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

Source

pub const fn time(&self) -> StateTime

Returns this state’s temporal coordinate.

Source

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:

Source

pub const fn schema(&self) -> &SystemStateSchema

Returns the shared immutable field specification.

Source

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.

Source

pub fn initialize_payload<T>( &mut self, key: &str, payload: T, ) -> Result<(), PayloadInsertError<T>>
where T: Serialize + Clone + Send + 'static,

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.

Source

pub fn insert_payload<T>( &mut self, key: &str, payload: T, ) -> Result<Option<T>, PayloadInsertError<T>>
where T: Serialize + Clone + Send + 'static,

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 returns Ok(None);
  • a slot bound to exactly T receives it and returns the displaced payload as Ok(Some(previous)), or Ok(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:

In both cases PayloadInsertError::into_parts recovers the unchanged incoming T without cloning it.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn take_payload<T>(&mut self, key: &str) -> Result<T, StateError>
where T: Any + Send,

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

Source

pub fn clone_structure_without_payloads(&self, time: StateTime) -> SystemState

Creates an empty state sharing schema and retained payload type contracts.

Source

pub fn replace_time(&mut self, time: StateTime) -> StateTime

Replaces the complete temporal coordinate and returns the previous one.

Source

pub fn populated_field_count(&self) -> usize

Returns the number of fields that currently contain payloads.

Source

pub fn payload_has_type<T: Any>(&self, key: &str) -> Result<bool, StateError>

Reports whether a populated field contains exactly T.

Source

pub fn clear_payload(&mut self, key: &str) -> Result<bool, StateError>

Drops one payload while retaining its field type contract.

Source

pub fn clear_all_payloads(&mut self)

Drops all payloads while retaining schema, time, and type contracts.

Trait Implementations§

Source§

impl Clone for SystemState

Source§

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)

Performs copy-assignment from source. Read more
Source§

impl Debug for SystemState

Source§

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats structural metadata without formatting scientific payloads.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.