DScale

A fast, deterministic simulation framework for testing and benchmarking distributed systems. It simulates network latency, bandwidth constraints, and process execution in an event-driven environment with support for both single-threaded and parallel execution modes.

Usage

1. Define Messages

Messages must implement the Message trait, which allows defining a virtual_size for bandwidth simulation.

use dscale::*;

#[derive(Debug)]
struct MyMessage {
    data: u32,
}

impl Message for MyMessage {
    fn virtual_size(&self) -> usize {
        // Size in bytes used for bandwidth simulation.
        // Can be much bigger than real memory size to simulate heavy payloads.
        1000
    }
}

// Or (if there is no need in bandwidth)
impl Message for MyMessage {}

2. Implement Process Logic

Implement Process to define how your process reacts to initialization, messages, and timers.

use dscale::*;

#[derive(Default)]
struct MyProcess;

impl Process for MyProcess {
    fn on_start(&mut self, _seed: Seed) {
        schedule_timer_after(Jiffies(100));
    }

    fn on_message(&mut self, from: Pid, message: MessagePtr) {
        if let Some(msg) = message.try_as_type::<MyMessage>() {
            dscale_debug!("Received message from {from}: {}", msg.data);
        }
    }

    fn on_timer(&mut self, _id: TimerId) {
        broadcast(MyMessage { data: 42 });
    }
}

3. Run the Simulation

Use SimulationBuilder to configure the topology, network constraints, and start the simulation.

use dscale::*;

fn main() {
    let mut runner = SimulationBuilder::new()
        .add_pool::<MyClient>("Client", 1)
        .add_pool::<MyServer>("Server", 3)
        .default_latency(Distr::Uniform{low: Jiffies(1), high: Jiffies(5)})
        .between_pool_latency("Client", "Server", Distr::Normal {
            mean: Jiffies(10),
            std_dev: Jiffies(2),
            low: Jiffies(5),
            high: Jiffies(20),
        })
        .vnic_bandwidth(BandwidthConfig::Bounded{inbound: 1000, outbound: 1000})
        .time_budget(Jiffies(1_000_000))
        .name("My simulation optional name")
        .seq_sched()
        .build();

    runner.run_full_budget();
}

Parallel Execution

For large simulations, enable parallel execution to distribute process steps across multiple threads:

let mut runner = SimulationBuilder::new()
    .add_pool::<MyProcess>("Nodes", 1000)
    .within_pool_latency("Nodes", Distr::Uniform{low: Jiffies(1), high: Jiffies(10)})
    .time_budget(Jiffies(1_000_000))
    .par_sched(ThreadNumber::Specific(8)) // use 8 worker threads
    .build();

runner.run_full_budget();

When is the parallel scheduler efficient?

1. A lot of simulated processes (at least 200-300)
2. on_message/on_timer execution takes most of the simulation time
3. Independent work inside on_message/on_timer handlers (not so much synchronization)

Omtimizations

For faster simulations we advise you to use these settings in your Cargo.toml:

[profile.release]
lto = "fat"           # Link Time Optimization: enables cross-crate optimizations
codegen-units = 1     # Reduces parallelism in code generation for better optimization
panic = "abort"       # Removes stack unwinding code, slightly smaller and faster binary

Fault Injection

DScale supports injecting network faults into simulations. Faults are scheduled as events — you specify when a fault starts and when it ends.

let mut runner = SimulationBuilder::new()
    .add_pool::<MyProcess>("Nodes", 5)
    .within_pool_latency("Nodes", Distr::Uniform{low: Jiffies(1), high: Jiffies(5)})
    .time_budget(Jiffies(1_000_000))
    // Break the link between pid 0 and pid 1 from time 100 to 500
    .break_link(Jiffies(100), Jiffies(500), 0, 1)
    // Isolate pid 2 (all links broken) from time 200 to 800
    .isolate(Jiffies(200), Jiffies(800), 2)
    .seq_sched()
    .build();

runner.run_full_budget();

Public API

Simulation Control

SimulationBuilder — Configures the simulation environment.

SimulationRunner

Network Topology

Constants

Distributions

Process Interaction (Context-Aware)

These functions are available globally but must be called within the context of a running process step.

Key-Value Store (dscale::services::kv)

Thread-safe store for passing shared state, metrics, or configuration between processes or back to the host.

[!WARNING]
(1) You can't call kv functions from a custom Default trait definition for your process. If it is the case, use the on_start handler. (2) High modify load on the same key(s) may introduce high contention and performance degradation when used with the parallel scheduler.

Macros

All logging macros prefix output with the current simulation time and process pid ([Now: ... | P...]). Controlled by the RUST_LOG environment variable.

Helpers (dscale::helpers)

Message Downcasting (MessagePtr)

Logging Configuration (RUST_LOG)

DScale output is controlled via the RUST_LOG environment variable.

• RUST_LOG=[some_level]: Enables all dscale_[level <= some_level]! macros output.
• RUST_LOG=full::path::to::your::file::or::crate=[level],another::path=[level]: Filter events only for your specific file or crate.

[!WARNING]
RUST_LOG=[level > info] only works without the --release flag.

Examples

You can find usage examples here

Paper

You can find paper describing algorithms behind dscale here

Thanks to

• https://gitlab.com/whirl-framework
• https://github.com/jepsen-io/maelstrom
• https://github.com/systems-group/anysystem
• https://www.nsnam.org
• https://omnetpp.org
• https://peersim.sourceforge.net