5 releases

Uses new Rust 2021

new 0.2.0-alpha.1 May 12, 2022
0.1.3 Nov 30, 2021
0.1.2 Nov 4, 2021
0.1.1 Aug 24, 2021
0.1.0 Aug 22, 2021

#108 in Asynchronous

Download history 4/week @ 2022-01-24 3/week @ 2022-01-31 1/week @ 2022-02-07 3/week @ 2022-02-14 4/week @ 2022-02-21 16/week @ 2022-03-14 12/week @ 2022-03-21 1/week @ 2022-03-28 2/week @ 2022-04-04 24/week @ 2022-04-25 28/week @ 2022-05-02 159/week @ 2022-05-09

211 downloads per month
Used in madsim-tonic

Apache-2.0

130KB
3K SLoC

MadSim

Crate Docs CI

Magical Deterministic Simulator for distributed systems.

Deterministic Simulation Testing

MadSim is a Rust async runtime similar to tokio, but with a key feature called deterministic simulation.

The main idea is borrowed from FoundationDB and sled simulation guide. Your code should be able to deterministically executed on top of a simulator. The simulator will amplify randomness, create chaos and inject failures into your system. A lot of hidden bugs may be revealed, which you can then deterministically reproduce them until they are fixed. If your system can survive such chaos, you will have more confidence in deploying your system in the real world.

However, implementing deterministic simulation is difficult. All I/O-related interfaces must be mocked during the simulation, and all uncertainties should be eliminated. This project is created to make that easy.

A part of the implementation of this crate is inspired by tokio-rs/simulation.

Usage

NOTE: The current version 0.2 is in preview. API may be changed in the future.

Add the following lines to your Cargo.toml:

[dependencies]
madsim = "0.2.0-alpha.1"

If your project depends on tonic, replace all tonic and tonic-build entries too:

[dependencies]
tonic = { version = "0.2.0-alpha.1", package = "madsim-tonic" }

[dev-dependencies]
tonic-build = { version = "0.2.0-alpha.1", package = "madsim-tonic-build" }

Next, redirect the following APIs to madsim:

use std::collections    -> use madsim::collections
use rand                -> use madsim::rand
use tokio::time         -> use madsim::time
use tokio::task         -> use madsim::task
use tokio::fs           -> use madsim::fs
use tokio::test         -> use madsim::test

When built normally, these APIs are identical to the original ones.

To test your code on the simulator, enable the sim feature of madsim:

cargo test --features=madsim/sim
# or the `sim` feature of tonic if you use it
cargo test --features=tonic/sim

Now you have gotten rid of tokio/tonic and you are in the simulation world!

We provide a set of APIs to control the simulator. You can use them to kill a process, disconnect the network, inject failures, etc. Check out the documentation and search for the sim feature to learn more usages.

Ensure determinism

Developers should eliminate any randomness in the application code. That's not easy.

Here are some tips to avoid randomness:

To make sure your code is deterministic, run your test with the following environment variable:

MADSIM_TEST_CHECK_DETERMINISM=1

Your test will be run at least twice with the same seed. If any non-determinism detected, it will panic as soon as possible.

Related Projects

  • MadRaft: The labs of Raft consensus algorithm derived from MIT 6.824 and PingCAP Talent Plan.

License

Apache License 2.0

Dependencies

~1.1–1.8MB
~35K SLoC