Struct SimWorld 

pub struct SimWorld { /* private fields */ }

The central simulation coordinator that manages time and event processing.

SimWorld owns all mutable simulation state and provides the main interface for scheduling events and advancing simulation time. It uses a centralized ownership model with handle-based access to avoid borrow checker conflicts.

Implementations

impl SimWorld

pub fn with_storage_config<F, R>(&self, f: F) -> R

where F: FnOnce(&StorageConfiguration) -> R,

Access storage configuration for the simulation.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn simulate_crash_for_process(&self, ip: IpAddr, close_files: bool)

Simulate a crash affecting storage for a specific process.

Only affects files owned by the given IP address:

1. Calls apply_crash() on matching InMemoryStorage instances
2. Clears pending operations (lost in crash)
3. Optionally marks files as closed
4. Wakes all storage wakers (operations will fail)

Files owned by other IPs are unaffected.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn wipe_storage_for_process(&self, ip: IpAddr)

Wipe all storage for a specific process.

Deletes all files owned by the given IP address. Used by CrashAndWipe reboot to simulate total data loss. After wipe, the process can create new files at the same paths.

Files owned by other IPs are unaffected.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn set_process_storage_config( &self, ip: IpAddr, config: StorageConfiguration, )

Set storage configuration for a specific process.

Files owned by this IP will use this configuration for fault injection and latency calculations. Takes effect immediately, even for files already open.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

impl SimWorld

pub fn new() -> Self

Creates a new simulation world with default network configuration.

Uses default seed (0) for reproducible testing. For custom seeds, use SimWorld::new_with_seed.

pub fn take_faults(&self) -> Vec<SimFaultRecord>

Drain engine-recorded faults accumulated since the last call.

The runner calls this after each step() to pump faults into the observability timeline; tests can call it directly to assert on the fault sequence.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn new_with_seed(seed: u64) -> Self

Creates a new simulation world with a specific seed for deterministic randomness.

This method ensures clean thread-local RNG state by resetting before setting the seed, making it safe for consecutive simulations on the same thread.

Parameters

• seed - The seed value for deterministic randomness

pub fn new_with_network_config(network_config: NetworkConfiguration) -> Self

Creates a new simulation world with custom network configuration.

pub fn new_with_network_config_and_seed( network_config: NetworkConfiguration, seed: u64, ) -> Self

Creates a new simulation world with both custom network configuration and seed.

Parameters

• network_config - Network configuration for latency and fault simulation
• seed - The seed value for deterministic randomness

pub fn step(&mut self) -> bool

Processes the next scheduled event and advances time.

Returns true if more events are available for processing, false if this was the last event or if no events are available.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn run_until_empty(&mut self)

Processes all scheduled events until the queue is empty or only infrastructure events remain.

This method processes all workload-related events but stops early if only infrastructure events (like connection restoration) remain. This prevents infinite loops where infrastructure events keep the simulation running indefinitely after workloads complete.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn current_time(&self) -> Duration

Returns the current simulation time.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn now(&self) -> Duration

Returns the exact simulation time (equivalent to FDB’s now()).

This is the canonical simulation time used for scheduling events. Use this for precise time comparisons and scheduling.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn timer(&self) -> Duration

Returns the drifted timer time (equivalent to FDB’s timer()).

The timer can be up to clock_drift_max (default 100ms) ahead of now(). This simulates real-world clock drift between processes, which is important for testing time-sensitive code like:

• Timeout handling
• Lease expiration
• Distributed consensus (leader election)
• Cache invalidation
• Heartbeat detection

FDB formula: timerTime += random01() * (time + 0.1 - timerTime) / 2.0

FDB ref: sim2.actor.cpp:1058-1064

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn schedule_event(&self, event: Event, delay: Duration)

Schedules an event to execute after the specified delay from the current time.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn schedule_event_at(&self, event: Event, time: Duration)

Schedules an event to execute at the specified absolute time.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn downgrade(&self) -> WeakSimWorld

Creates a weak reference to this simulation world.

Weak references can be used to access the simulation without preventing it from being dropped, enabling handle-based access patterns.

pub fn has_pending_events(&self) -> bool

Returns true if there are events waiting to be processed.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn pending_event_count(&self) -> usize

Returns the number of events waiting to be processed.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn network_provider(&self) -> SimNetworkProvider

Create a network provider for this simulation

pub fn time_provider(&self) -> SimTimeProvider

Create a time provider for this simulation

pub fn task_provider(&self) -> SimTaskProvider

Create a task provider for this simulation

pub fn storage_provider(&self, ip: IpAddr) -> SimStorageProvider

Create a storage provider for this simulation scoped to a process IP.

pub fn set_storage_config(&mut self, config: StorageConfiguration)

Set the default storage configuration for this simulation.

Used as fallback when no per-process config is set for a given IP.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn set_storage_config_for( &mut self, ip: IpAddr, config: StorageConfiguration, )

Set the storage configuration for a single process IP.

Overrides the default (set_storage_config) for files owned by ip, letting different machines run with different storage timing and fault profiles in the same simulation.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn disk_episode_for(&self, ip: IpAddr) -> Option<DiskDegradationState>

Active disk-degradation episode for a process IP, if any.

Episodes are scoped per owner: one stall/throttle window applies to every file the process owns. Observability accessor for tests and diagnostics.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn with_network_config<F, R>(&self, f: F) -> R

where F: FnOnce(&NetworkConfiguration) -> R,

Access network configuration for latency calculations using thread-local RNG.

This method provides access to the network configuration for calculating latencies and other network parameters. Random values should be generated using the thread-local RNG functions like sim_random().

Access the network configuration for this simulation.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn sleep(&self, duration: Duration) -> SleepFuture

Sleep for the specified duration in simulation time.

Returns a future that will complete when the simulation time has advanced by the specified duration.

pub fn assertion_results(&self) -> HashMap<String, AssertionStats>

Get current assertion results for all tracked assertions.

pub fn reset_assertion_results(&self)

Reset assertion statistics to empty state.

pub fn abort_all_connections_for_ip(&self, ip: IpAddr)

Abort all connections involving a specific IP address.

This is used during process reboot to immediately kill all network connections for the rebooted process. Both local and remote connections are aborted (RST semantics — peer sees ECONNRESET).

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn schedule_process_restart(&self, ip: IpAddr, recovery_delay: Duration)

Schedule a ProcessRestart event after a recovery delay.

Called after a process is killed to schedule its restart.

pub fn last_processed_event(&self) -> Option<Event>

Returns the last event processed by step(), if any.

This is used by the orchestrator to detect ProcessRestart events and handle them (respawn the process).

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn extract_metrics(&self) -> SimulationMetrics

Extract simulation metrics (simulated time, events processed).

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn should_clog_write(&self, connection_id: ConnectionId) -> bool

Check if a write should be clogged based on probability

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn clog_write(&self, connection_id: ConnectionId)

Clog a connection’s write operations

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn is_write_clogged(&self, connection_id: ConnectionId) -> bool

Check if a connection’s writes are currently clogged

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn register_clog_waker(&self, connection_id: ConnectionId, waker: Waker)

Register a waker for when write clog clears

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn should_clog_read(&self, connection_id: ConnectionId) -> bool

Check if a read should be clogged based on probability

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn clog_read(&self, connection_id: ConnectionId)

Clog a connection’s read operations

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn is_read_clogged(&self, connection_id: ConnectionId) -> bool

Check if a connection’s reads are currently clogged

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn register_read_clog_waker( &self, connection_id: ConnectionId, waker: Waker, )

Register a waker for when read clog clears

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn clear_expired_clogs(&self)

Clear expired clogs and wake pending tasks

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn is_connection_cut(&self, connection_id: ConnectionId) -> bool

Check if a connection is temporarily cut.

A cut connection is temporarily unavailable but will be restored. This is different from is_connection_closed which indicates permanent closure.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn register_cut_waker(&self, connection_id: ConnectionId, waker: Waker)

Register a waker for when a cut connection is restored.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn send_buffer_capacity(&self, connection_id: ConnectionId) -> usize

Get the send buffer capacity for a connection.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn send_buffer_used(&self, connection_id: ConnectionId) -> usize

Get the current send buffer usage for a connection.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn available_send_buffer(&self, connection_id: ConnectionId) -> usize

Get the available send buffer space for a connection.

pub fn register_send_buffer_waker( &self, connection_id: ConnectionId, waker: Waker, )

Register a waker for when send buffer space becomes available.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn pair_latency(&self, src: IpAddr, dst: IpAddr) -> Option<Duration>

Get the base latency for a connection pair. Returns the latency if already set, otherwise None.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn set_pair_latency_if_not_set( &self, src: IpAddr, dst: IpAddr, latency: Duration, ) -> Duration

Set the base latency for a connection pair if not already set. Returns the latency (existing or newly set).

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn connection_base_latency(&self, connection_id: ConnectionId) -> Duration

Get the permanent per-pair base latency for a connection, memoizing it on first contact (FDB SimClogging).

Returns Duration::ZERO — without drawing from the RNG or touching the pair map — when the max_pair_latency range is disabled (its end is zero) or the connection’s endpoints are unknown. Otherwise samples a fixed latency from max_pair_latency once per ordered IP pair and reuses it for the run.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn send_delay(&self, connection_id: ConnectionId) -> Option<Duration>

Get the send delay for a connection. Returns the per-connection override if set, otherwise None.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn recv_delay(&self, connection_id: ConnectionId) -> Option<Duration>

Get the receive delay for a connection. Returns the per-connection override if set, otherwise None.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn is_connection_closed(&self, connection_id: ConnectionId) -> bool

Check if a connection is permanently closed

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn close_connection(&self, connection_id: ConnectionId)

Close a connection gracefully (FIN semantics).

The peer will receive EOF on read operations.

pub fn close_connection_abort(&self, connection_id: ConnectionId)

Close a connection abruptly (RST semantics).

The peer will receive ECONNRESET on both read and write operations.

pub fn close_reason(&self, connection_id: ConnectionId) -> CloseReason

Get the close reason for a connection.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn close_connection_asymmetric( &self, connection_id: ConnectionId, close_send: bool, close_recv: bool, )

Close connection asymmetrically (FDB rollRandomClose pattern)

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn roll_random_close(&self, connection_id: ConnectionId) -> Option<bool>

Roll random close chaos injection (FDB rollRandomClose pattern)

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn is_send_closed(&self, connection_id: ConnectionId) -> bool

Check if a connection’s send side is closed

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn is_recv_closed(&self, connection_id: ConnectionId) -> bool

Check if a connection’s receive side is closed

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn is_remote_fin_received(&self, connection_id: ConnectionId) -> bool

Check if a FIN has been received from the remote peer (graceful close).

When true, poll_read should return EOF after draining the receive buffer. Distinct from is_recv_closed which is used for chaos/asymmetric closure.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn is_half_open(&self, connection_id: ConnectionId) -> bool

Check if a connection is in half-open state

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn should_half_open_error(&self, connection_id: ConnectionId) -> bool

Check if a half-open connection should return errors now

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn mark_connection_stable(&self, connection_id: ConnectionId)

Mark a connection as stable, exempting it from chaos injection.

Stable connections are exempt from:

• Random close (roll_random_close)
• Write clogging
• Read clogging
• Bit flip corruption
• Partial write truncation

FDB ref: sim2.actor.cpp:357-362 (stableConnection flag)

Real-World Scenario

Use this for parent-child process connections or supervision channels that should remain reliable even during chaos testing.

Panics

Panics if the simulation lock is poisoned by a prior task panic.

pub fn partition_pair( &self, from_ip: IpAddr, to_ip: IpAddr, duration: Duration, ) -> SimulationResult<()>

Partition communication between two IP addresses for a specified duration

Panics

Panics if the simulation lock is poisoned by a prior task panic.

Errors

Returns an error if the operation is rejected by the simulator (for example, the simulation has not been started).

pub fn partition_send_from( &self, ip: IpAddr, duration: Duration, ) -> SimulationResult<()>

Block all outgoing communication from an IP address

Panics

Panics if the simulation lock is poisoned by a prior task panic.

Errors

Returns an error if the operation is rejected by the simulator (for example, the simulation has not been started).

pub fn partition_recv_to( &self, ip: IpAddr, duration: Duration, ) -> SimulationResult<()>

Block all incoming communication to an IP address

Panics

Panics if the simulation lock is poisoned by a prior task panic.

Errors

Returns an error if the operation is rejected by the simulator (for example, the simulation has not been started).

pub fn restore_partition( &self, from_ip: IpAddr, to_ip: IpAddr, ) -> SimulationResult<()>

Immediately restore communication between two IP addresses

Panics

Panics if the simulation lock is poisoned by a prior task panic.

Errors

Returns an error if the operation is rejected by the simulator (for example, the simulation has not been started).

pub fn is_partitioned( &self, from_ip: IpAddr, to_ip: IpAddr, ) -> SimulationResult<bool>

Check if communication between two IP addresses is currently partitioned

Panics

Panics if the simulation lock is poisoned by a prior task panic.

Errors

Returns an error if the operation is rejected by the simulator (for example, the simulation has not been started).

Trait Implementations

impl Debug for SimWorld

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

Formats the value using the given formatter.

impl Default for SimWorld

fn default() -> Self

Returns the “default value” for a type.