Struct Sim

pub struct Sim<'a> { /* private fields */ }

A handle for interacting with the simulation.

Implementations

impl<'a> Sim<'a>

pub fn elapsed(&self) -> Duration

How much logical time has elapsed since the simulation started.

pub fn since_epoch(&self) -> Duration

The logical duration from UNIX_EPOCH until now.

On creation the simulation picks a SystemTime and calculates the duration since the epoch. Each run() invocation moves logical time forward the configured tick duration.

pub fn client<F>(&mut self, addr: impl ToIpAddr, client: F)

where F: Future<Output = Result> + 'static,

Register a client with the simulation.

pub fn host<F, Fut>(&mut self, addr: impl ToIpAddr, host: F)

where F: Fn() -> Fut + 'a, Fut: Future<Output = Result> + 'static,

Register a host with the simulation.

This method takes a Fn that builds a future, as opposed to Sim::client which just takes a future. The reason for this is we might restart the host, and so need to be able to call the future multiple times.

pub fn crash(&mut self, addrs: impl ToIpAddrs)

Crashes the resolved hosts. Nothing will be running on the matched hosts after this method. You can use Sim::bounce to start the hosts up again.

pub fn bounce(&mut self, addrs: impl ToIpAddrs)

Bounces the resolved hosts. The software is restarted.

pub fn is_host_running(&mut self, addr: impl ToIpAddr) -> bool

Check whether a host has software running.

pub fn lookup(&self, addr: impl ToIpAddr) -> IpAddr

Lookup an IP address by host name.

pub fn reverse_lookup(&self, addr: IpAddr) -> Option<String>

Perform a reverse DNS lookup, returning the hostname if the entry exists.

pub fn hold(&self, a: impl ToIpAddrs, b: impl ToIpAddrs)

Hold messages between two hosts, or sets of hosts, until release is called.

pub fn repair(&self, a: impl ToIpAddrs, b: impl ToIpAddrs)

Repair the connection between two hosts, or sets of hosts, resulting in messages to be delivered.

pub fn repair_oneway(&self, from: impl ToIpAddrs, to: impl ToIpAddrs)

Repair the connection between two hosts, or sets of hosts, removing the effect of a previous Self::partition_oneway.

Combining this feature with Self::hold is presently not supported.

pub fn release(&self, a: impl ToIpAddrs, b: impl ToIpAddrs)

The opposite of hold. All held messages are immediately delivered.

pub fn partition(&self, a: impl ToIpAddrs, b: impl ToIpAddrs)

Partition two hosts, or sets of hosts, resulting in all messages sent between them to be dropped.

pub fn partition_oneway(&self, from: impl ToIpAddrs, to: impl ToIpAddrs)

Partition two hosts, or sets of hosts, such that messages can not be sent from ‘from’ to ‘to’, while not affecting the ability for them to be delivered in the other direction.

Partitioning first from->to, then to->from, will stop all messages, similarly to a single call to Self::partition.

Combining this feature with Self::hold is presently not supported.

pub fn reverse_lookup_pair(&self, pair: (IpAddr, IpAddr)) -> (String, String)

Resolve host names for an IpAddr pair.

Useful when interacting with network links.

pub fn lookup_many(&self, addr: impl ToIpAddrs) -> Vec<IpAddr>

Lookup IP addresses for resolved hosts.

pub fn set_max_message_latency(&self, value: Duration)

Set the max message latency for all links.

pub fn set_link_latency( &self, a: impl ToIpAddrs, b: impl ToIpAddrs, value: Duration, )

Set the message latency for any links matching a and b.

This sets the min and max to the same value eliminating any variance in latency.

pub fn set_link_max_message_latency( &self, a: impl ToIpAddrs, b: impl ToIpAddrs, value: Duration, )

Set the max message latency for any links matching a and b.

pub fn set_message_latency_curve(&self, value: f64)

Set the message latency distribution curve for all links.

Message latency follows an exponential distribution curve. The value is the lambda argument to the probability function.

pub fn set_fail_rate(&mut self, value: f64)

pub fn set_link_fail_rate( &mut self, a: impl ToIpAddrs, b: impl ToIpAddrs, value: f64, )

pub fn links(&self, f: impl FnOnce(LinksIter<'_>))

Access a LinksIter to introspect inflight messages between hosts.

pub fn run(&mut self) -> Result

Run the simulation until all client hosts have completed.

Executes a simple event loop that calls step each iteration, returning early if any host software errors.

pub fn step(&mut self) -> Result<bool>

Step the simulation.

Runs each host in the simulation a fixed duration configured by tick_duration in the builder.

The simulated network also steps, processing in flight messages, and delivering them to their destination if appropriate.

Returns whether or not all clients have completed.