Struct RealtimeAsyncWorld 

pub struct RealtimeAsyncWorld { /* private fields */ }

Realtime asynchronous simulation world.

Runs the tick engine on a background thread and serves observations from a pool of egress workers. This is the primary API for RL training environments.

Implementations

impl RealtimeAsyncWorld

pub fn new( config: WorldConfig, async_config: AsyncConfig, ) -> Result<Self, ConfigError>

Create a new realtime async world and spawn all threads.

The WorldConfig is consumed: the TickEngine is moved into the tick thread. The space is shared via Arc for egress workers that need it for agent-relative observations.

pub fn submit_commands( &self, commands: Vec<Command>, ) -> Result<Vec<Receipt>, SubmitError>

Submit commands to be processed in the next tick.

Non-blocking: sends the batch via channel and blocks only for the receipt reply (which arrives within one tick period).

pub fn observe( &self, plan: &Arc<ObsPlan>, output: &mut [f32], mask: &mut [u8], ) -> Result<ObsMetadata, ObsError>

Extract an observation from the latest snapshot.

Blocking: dispatches to an egress worker and waits for the result. The output and mask buffers must be pre-allocated.

pub fn observe_agents( &self, plan: &Arc<ObsPlan>, space: &Arc<dyn Space>, agent_centers: &[Coord], output: &mut [f32], mask: &mut [u8], ) -> Result<Vec<ObsMetadata>, ObsError>

Extract agent-relative observations from the latest snapshot.

Each agent gets output_len / n_agents elements in the output buffer.

pub fn latest_snapshot(&self) -> Option<Arc<OwnedSnapshot>>

Get the latest snapshot directly from the ring.

pub fn current_epoch(&self) -> u64

Current epoch (lock-free read).

pub fn shutdown(&mut self) -> ShutdownReport

Shutdown the world with the 4-state machine.

1. Running → Draining (≤33ms): Set shutdown flag, wait for tick stop.
2. Draining → Quiescing (≤200ms): Cancel workers, drop obs channel.
3. Quiescing → Dropped (≤10ms): Join all threads.

pub fn reset(&mut self, seed: u64) -> Result<(), ConfigError>

Reset the world: stop all threads, reset engine state, restart.

This is the RL episode-boundary operation. The engine is recovered from the tick thread, reset in-place, then respawned with fresh channels and worker threads.

pub fn space(&self) -> &dyn Space

The shared space used for agent-relative observations.

Trait Implementations

impl Drop for RealtimeAsyncWorld

fn drop(&mut self)

Executes the destructor for this type.