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 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 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.

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.

pub fn current_time(&self) -> Duration

Returns the current simulation time.

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.

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

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

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

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

Schedules an event to execute at the specified absolute time.

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.

pub fn pending_event_count(&self) -> usize

Returns the number of events waiting to be processed.

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) -> TokioTaskProvider

Create a task provider for this simulation

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.

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 extract_metrics(&self) -> SimulationMetrics

Extract simulation metrics for reporting.

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

Check if a write should be clogged based on probability

pub fn clog_write(&self, connection_id: ConnectionId)

Clog a connection’s write operations

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

Check if a connection’s writes are currently clogged

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

Register a waker for when write clog clears

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

Check if a read should be clogged based on probability

pub fn clog_read(&self, connection_id: ConnectionId)

Clog a connection’s read operations

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

Check if a connection’s reads are currently clogged

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

Register a waker for when read clog clears

pub fn clear_expired_clogs(&self)

Clear expired clogs and wake pending tasks

pub fn cut_connection(&self, connection_id: ConnectionId, duration: Duration)

Temporarily cut a connection for the specified duration.

Unlike close_connection, a cut connection will be automatically restored after the duration expires. This simulates temporary network outages where the underlying connection remains but is temporarily unavailable.

During a cut:

• poll_read returns Poll::Pending (waits for restore)
• poll_write returns Poll::Pending (waits for restore)
• Buffered data is preserved

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.

pub fn restore_connection(&self, connection_id: ConnectionId)

Restore a cut connection immediately.

This cancels the cut state and wakes any tasks waiting for restoration.

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

Register a waker for when a cut connection is restored.

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

Get the send buffer capacity for a connection.

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

Get the current send buffer usage for a connection.

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.

pub fn get_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.

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).

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

Get the base latency for a connection based on its IP pair. If not set, samples from config and sets it.

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

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

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

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

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

Set asymmetric delays for a connection. If a delay is None, the global configuration is used instead.

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

Check if a connection is permanently closed

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 get_close_reason(&self, connection_id: ConnectionId) -> CloseReason

Get the close reason for a connection.

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

Close connection asymmetrically (FDB rollRandomClose pattern)

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

Roll random close chaos injection (FDB rollRandomClose pattern)

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

Check if a connection’s send side is closed

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

Check if a connection’s receive side is closed

pub fn simulate_peer_crash( &self, connection_id: ConnectionId, error_delay: Duration, )

Simulate a peer crash on a connection.

This puts the connection in a half-open state where:

• The local side still thinks it’s connected
• Writes succeed but data is silently discarded (peer is gone)
• Reads block waiting for data that will never come
• After error_delay, both read and write return ECONNRESET

This simulates real-world scenarios where a remote peer crashes or becomes unreachable, but the local TCP stack hasn’t detected it yet.

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

Check if a connection is in half-open state

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

Check if a half-open connection should return errors now

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

Partition communication between two IP addresses for a specified duration

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

Block all outgoing communication from an IP address

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

Block all incoming communication to an IP address

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

Immediately restore communication between two IP addresses

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

Check if communication between two IP addresses is currently partitioned

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.