A Minimalistic Simulation Framework in Rust

Introduction

This Rust project provides a minimally-viable library for creating and running simulations using asynchronous processes. By leveraging Rust's concurrency features, it allows you to simulate various scenarios, making it a valuable tool for studying the mechanics of simulation libraries in projects involving complex, process-based models.

This simulation core is not meant to be used in production code, see odem-rs for an earnest attempt.

Features

The project includes:

• Core Library (lib.rs): Defines reusable components for building simulators.
• Utility Modules (util.rs): Provides support for common simulation tasks.
• Example Models: Demonstrates different aspects of the framework through three examples:
  • barbershop
  • ferry
  • philosophers
• Decompressor-Tokenizer (bin/coroutines.rs): An educational example with an executor, a corresponding spawner, and a channel that shows the mechanism without using unsafe code.
• Decompressor-Tokenizer (c/coroutines.c): The same example implemented manually in C to illustrate the transformation performed by the Rust compiler on async/await.

Getting Started

Prerequisites

• Rust Compiler: Latest stable version is recommended. Install Rust
• no other dependencies

Building the Project

To build the project, run:

cargo build

Running the Examples

The examples are located in the examples directory and demonstrate different types of simulations:

• Barbershop: A discrete event simulation of a barbershop where customers arrive randomly, wait if the barber is busy, receive service, and depart. It tracks customer wait times and provides statistical analysis over the simulated period. This is a minimalistic model containing processes and time- and state-based synchronization.

• Ferry: Simulates a car-ferry system where cars arrive at multiple harbors and wait to be transported by ferries to other harbors. It tracks statistics like car wait times, ferry cargo lengths, and ferry load times. This example demonstrates complex synchronization, featuring channels and speculative execution.

• Philosophers: Simulates the classic Dining Philosophers problem, where philosophers alternate between thinking and eating, requiring coordination to avoid deadlocks. It tracks the time until a deadlock occurs and collects statistical data over multiple simulation runs. This example highlights parallel execution of multiple simulations and concurrent resource access.

To run an example, use:

cargo run --example <example_name>

For example, to run the barbershop simulation:

cargo run --example barbershop

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

Special thanks to the contributors of the Rust community for creating powerful tools that make projects like this possible. Extra-special thanks to Lukas Markeffsky for helping me to refine this library both through fruitful discussions and by resolving its soundness problems through a refactoring of the code.