# A Closer Look at Process-Based Simulation with Stackless Coroutines
# A Minimalistic Simulation Framework in Rust
## Overview
This repository contains the source code for the simulator core discussed in our IST 2021 paper as well as code needed to run and benchmark the sample scenarios from the paper.
## Introduction
In order to run the examples and benchmarks, you should install the [Rust-compiler], SLX and a C++ compiler first.
Any C++-14 conforming compiler should work, the ODEMx-library is translated using Rust-code that searches for a compiler first, so the popular compilers `msvc`, `clang`, `mingw` and `gcc` should work out of the box.
This Rust project provides a framework 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-driven models.
Unfortunately, there is no way to get SLX at the moment, as the creator James O. Henriksen passed away in 2020, and the company's original website has vanished.
## Features
We are unsure if it would be legal for us to provide you with the demo version in the context of this repository, so we opted against it.
Please contact us if you wish to obtain the free version of SLX for your own benchmarks.
The project includes:
The `src/` directory contains the source code for our simulator core *simcore-rs* as well as the decompressor-tokenizer example from the paper.
-**Core Library (`lib.rs`)**: Defines reusable components for building simulators.
The folder `examples/` contains the *Barbershop*, *Car Ferry* and *Dining Philosopher* examples including the code used to generate the comparative benchmarks.
-**Utility Modules (`util.rs`)**: Provides support for common simulation tasks.
In `slx/` one can find the SLX-code for the same examples, also including benchmarking provisions in the form of (real time) measurements.
-**Example Models**: Demonstrates different aspects of the framework through three examples:
The `c/` folder contains the manually transformed version of the decompressor-tokenizer example into coroutines in C as well as a `Makefile` for compilation.
-`barbershop`
The `cpp/` folder contains three sub-projects for the three examples that use ODEMx.
-`ferry`
The `results/` directory contains the complete report for our benchmarking results.
-`philosophers`
Finally, the `odemx-lite/` folder contains a clean version of ODEMx, that has all external dependencies stripped and only requires a C++-14 conforming compiler to be translated.
-**SLX Code (`slx`)**: Contains SLX code for the same examples, including benchmarking provisions with real-time measurements.
-**C++ Code (`cpp`)**: Contains three subprojects for the examples using ODEMx.
## Executing the Sample Code
-**C Code (`c`)**: Demonstrates the transformation of an ordinary routine into a coroutine for a decompressor-tokenizer example.
You may execute the decompressor-tokenizer example using `cargo run --bin coroutines` and the other examples using `cargo run --example <name>` for `<name>` in [*barbershop*, *ferry*, *philosophers*].
-**ODEMx (`odemx-lite`)**: A clean version without dependencies, compiled using a C++14-conforming compiler to run benchmarks.
For the analogous example in C, change into the `c/` directory and call `make run`. Note that the example reads from `stdin`, so this path requires manual input from the terminal.
For the benchmarks enter `cargo bench` into your terminal (or `cargo bench --example <name>` if you wish to run a specific benchmark).
## Getting Started
Cargo will download and compile all the dependencies automatically.
### Prerequisites
Should you wish to execute the SLX code as well, you will need to obtain a version of SLX first.
The free student version is sufficient to run the benchmarks but is about 30% slower than the full version of SLX due to its generation of 32-bit binaries rather than 64-bit binaries like the full version does.
-**Rust Compiler**: Latest stable version is recommended. [Install Rust][Rust-compiler]
-**C++14-Conforming Compiler**: Required for the ODEMx benchmarks. Popular compilers like MSVC, Clang, MinGW, and GCC should work out of the box.
## Benchmarks
-**SLX Compiler**: Required for the SLX benchmarks (both student and full versions work).
We executed the benchmarks under Windows 10 on an Intel Core i7-10750H processor with 6 cores (12 with hyper-threading) and 32 GB DDR4 RAM with activated link-time optimizations and optimization level 3.
#### Note on SLX Compiler
You can find the results under `results/criterion/report/index.html` for all three simulation systems.
Currently, obtaining the SLX compiler may be challenging because the creator, James O. Henriksen, passed away in 2020, and the company's original website is no longer available. If you wish to obtain the free version of SLX for benchmarking, please contact me directly.
### Building the Project
To build the project, run:
```sh
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:
```sh
cargo run --example <example_name>
```
For example, to run the barbershop simulation:
```sh
cargo run --example barbershop
```
## License
This project is licensed under the MIT License. See the [LICENSE](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.
