diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 112 |
1 files changed, 95 insertions, 17 deletions
@@ -3,12 +3,9 @@ <img src="misc/artwork/logo.png" width="100" alt="OpenDC"> </a> <br> - OpenDC Simulator + odcsim </h1> <p align="center"> -Collaborative Datacenter Simulation and Exploration for Everybody -</p> -<p align="center"> <a href="https://travis-ci.org/atlarge-research/opendc-simulator"> <img src="https://travis-ci.org/atlarge-research/opendc-simulator.svg?branch=master" alt="Build Status"> </a> @@ -17,22 +14,103 @@ Collaborative Datacenter Simulation and Exploration for Everybody </a> </p> -## Getting the source -Download the source code by running the following code in your command prompt: -```sh -$ git clone https://github.com/atlarge-research/opendc-simulator.git +## Introduction +**odcsim** is a framework for discrete event simulation in Kotlin and Java, used +by the [OpenDC](https://opendc.org) project. +Simulations are defined in terms of a hierarchical grouping of actors +and the interactions between these actors +([Actor model](https://en.wikipedia.org/wiki/Actor_model)), using +an API very similar to [Akka Typed](https://doc.akka.io/docs/akka/current/typed/index.html). + +## Documentation +Check out the [Getting Started](#getting-started) section for a quick +overview. +The documentation is located in the [docs/](docs/) directory and is divided as follows: +* [Main Concepts](docs/concepts.md) +* [Building a Model](docs/build.md) +* [Running a Model](docs/run.md) +* [Pre-built Models](docs/models.md) +* [API Reference](https://atlarge-research.github.io/opendc-simulator) +* [Contributing Guide](CONTRIBUTING.md) + +## Getting Started + +### Installation +Please add the required packages as dependency in your project. +Releases are available in the [Maven Central Repository](https://search.maven.org/). + +The package `odcsim-core` is required to construct a simulation model. +A `odcsim-engine-*` package is needed for running the simulation +model. + +**Gradle** +```groovy +compile 'com.atlarge.odcsim:odcsim-core:2.0.0' +compile 'com.atlarge.odcsim:odcsim-engine-omega:2.0.0' ``` -or simply [grab](https://github.com/atlarge-research/opendc-simulator/archive/master.zip) a copy of the source code as a Zip file. -## Building -For building the source code, we use Gradle. To run gradle, enter the following in your command prompt: -```sh -$ ./gradlew build +**Maven** +```xml +<dependency> + <groupId>com.atlarge.odcsim</groupId> + <artifactId>odcsim-core</artifactId> + <version>2.0.0</version> +</dependency> + +<dependency> + <groupId>com.atlarge.odcsim</groupId> + <artifactId>odcsim-engine-omega</artifactId> + <version>2.0.0</version> +</dependency> ``` -To test the source code, run the following code in your command prompt: + +### Construction of Simulation Model +Let's construct a simple simulation model of a single car actor. +The car will alternately drive and park for a while. When it starts +driving (or parking), it will print the current simulation time. + + +```kotlin +import com.atlarge.odcsim.Behavior +import com.atlarge.odcsim.coroutines.suspending +import com.atlarge.odcsim.coroutines.dsl.timeout + +fun car(): Behavior<Nothing> = + suspending { ctx -> + while (true) { + println("Start parking at ${ctx.time}") + val parkingDuration = 5.0 + timeout(parkingDuration) + + println("Start driving at ${ctx.time}") + val tripDuration = 2.0 + timeout(tripDuration) + } + + stopped() + } ``` -$ ./gradlew test + +### Running Simulation +Running the constructed simulation model requires an implementation +of the `ActorSystem` interface provided by one of the `odcsim-engine-*` +packages. The [ServiceLoader](https://docs.oracle.com/javase/9/docs/api/java/util/ServiceLoader.html) +class found in the JDK can be used to locate the `ActorSystem` implementation on the classpath. +```kotlin +import com.atlarge.odcsim.ActorSystemFactory +import java.util.ServiceLoader + +val factory = ServiceLoader.load(ActorSystemFactory::class.java).first() +val system = factory(car(), name = "car") +system.run(until = 10.0) +system.terminate() ``` -## License -The code is released under the MIT license. See the `LICENSE.txt` file. +## Contributing +### Contributing Guide +Read our [contributing guide](CONTRIBUTING.md) to learn about our +development process, how to propose bug fixes and improvements, and how +to build and test your changes to the project. + +### License +**odcsim** is [MIT licensed](https://github.com/atlarge-research/opendc-simulator/blob/master/LICENSE.txt). |