From 4ad068f741321973a70f10755074505a3f813ebd Mon Sep 17 00:00:00 2001 From: Georgios Andreadis Date: Fri, 14 Feb 2020 12:28:20 +0100 Subject: Add documentation for the odcsim component --- docs/architecture.md | 14 ++++++++++++-- docs/introduction.md | 1 - docs/run.md | 1 - docs/setup.md | 5 ----- 4 files changed, 12 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/architecture.md b/docs/architecture.md index 60ac3e0d..834de69c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,13 +1,23 @@ # 3. Architecture Overview - -The OpenDC simulator has two main components: `odcsim`, a general framework for discrete event-based simulation, and `opendc` a collection of components using `odcsim` to simulate datacenters. We discuss both in turn! +The OpenDC simulator has two main components: `odcsim`, a general framework for discrete event-based simulation, and `opendc` a collection of components using `odcsim` to simulate datacenters. While `opendc` is the focus of this project and thus these docs, we also shortly explain what `odcsim` looks like, to give you a better understanding of the other concepts. `TODO: Add a schematic general overview here.` ## 3.1 `odcsim` +The `odcsim` framework has an API module (`odcsim-api`) and an module implementing this API (`odcsim-engine-omega`). + +### 3.1.1 `odcsim-api` +The API defines the behavior of any implementation adhering to the `odcsim` framework. It centers around a `SimulationEngine`, which can be created through a `SimulationEngineProvider`. + +A simulation has a root process with certain `Behavior` (a coroutine). Processes have a `ProcessContext` which allow them to spawn other processes and open communication `Channel`s with other processes. Each of these `Channel`s has a `SendPort` and a `ReceivePort`. + +### 3.1.2 `odcsim-engine-omega` +The implementation is an executable interpretation of this API. The main class is `OmegaSimulationEngine` and takes care of transmitting timestamped events between processes. It ensures that message delivery order is the same as sent order. +You might note that the simulation framework and the simulator itself makes extensive use of Kotlin's coroutine feature. This is a paradigm for asynchronous programming. If you are not familiar with coroutines, we suggest having a look at the [Kotlin documentation on this](https://kotlinlang.org/docs/reference/coroutines-overview.html), especially their [quick start guide](https://kotlinlang.org/docs/tutorials/coroutines/coroutines-basic-jvm.html) and their [hands-on guide](https://play.kotlinlang.org/hands-on/Introduction%20to%20Coroutines%20and%20Channels/01_Introduction). ## 3.2 `opendc` +The `opendc` package consists of **TODO: What are the main components (odcsim-core, odcsim-engine, opendc-core, opendc-format, opendc-testkit, opendc-workflows, I assume)? Short description of each in a bullet list (or even a schema drawing, if you have the time). Why this division?** diff --git a/docs/introduction.md b/docs/introduction.md index e6e3289d..711a829b 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -1,5 +1,4 @@ # 1. Introduction - This repository hosts the source code and development of the simulation component of the [OpenDC](https://opendc.org) project. OpenDC is a simulation platform for cloud infrastructure, with the aim of making datacenter concepts and technology accessible to everyone. To learn more about OpenDC, have a look through our [vision paper](https://ieeexplore.ieee.org/document/8121623)! The simulator is one of the components of the OpenDC stack. It is responsible for modelling and simulation of datacenters and their components. This entails receiving environments and experiment configurations from up the stack, simulating these configurations, and reporting back results. diff --git a/docs/run.md b/docs/run.md index 1eadfedf..76be70ba 100644 --- a/docs/run.md +++ b/docs/run.md @@ -1,5 +1,4 @@ # 4. Running an Experiment - **TODO: What did we do for SC18?** --- diff --git a/docs/setup.md b/docs/setup.md index 0c5d412a..801dfe58 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,5 +1,4 @@ # 2. Toolchain Setup - The OpenDC simulator is built using the [Kotlin](https://kotlinlang.org/) language. This is a JVM-based language that should appear familiar to programmers knowledgeable in Java or Scala. For a short interactive introduction to Kotlin, the [Learn Kotlin By Example](https://play.kotlinlang.org/byExample/overview) docs are a great place to start. For the build and dependency toolchain, we use [Gradle](https://gradle.org/). You will likely not need to change the Gradle build configurations of components, but you will use Gradle to execute builds and tests on the codebase. @@ -7,21 +6,17 @@ For the build and dependency toolchain, we use [Gradle](https://gradle.org/). Yo Follow the steps below to get it all set up! ## 2.1 Installing Java - Kotlin requires a Java installation of version 8 or higher. Make sure to install the [JDK](https://www.oracle.com/technetwork/java/javase/downloads/index.html), not only the JRE (the JDK also includes a JRE). ## 2.2 Building and Developing - With Java installed, we're ready to set up the development environment on your machine. You can either use a visual IDE or work from a command line shell. We outline both approaches below, feel free to choose which you are most comfortable with. If in doubt which one to choose, we suggest going with the first one. ## 2.2.1 Setup With IntelliJ IDEA - We suggest using [IntelliJ IDEA](https://www.jetbrains.com/idea/) as development environment. Once you have installed any version of this IDE on your machine, choose "Get from Version Control" in the new project dialogue. Enter `https://atlarge.ewi.tudelft.nl/gitlab/opendc/opendc-simulator` as URL and submit your credentials when asked. Open the project once it's ready fetching the codebase, and let it set up with the defaults (IntelliJ will recognize that this is a Gradle codebase). You will now be prompted in a dialogue to enable auto-import for Gradle, which we suggest you do. Wait for any progress bars in the lower bar to disappear and then look for the Gradle context menu on the right hand side. In it, go to `opendc-simulator > Tasks > verification > test`. This will build the codebase and run checks to verify that tests pass. If you get a `BUILD SUCCESSFUL` message, you're ready to go to the [next section](architecture.md)! ## 2.2.2 Setup With Command Line - First, clone the repository with the following command: ```shell script -- cgit v1.2.3