blob: 54fa77cb40d3011a229e69c3e54cfea8b7bf1885 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
<h1 align="center">
<a href="http://opendc.org/">
<img src="misc/artwork/logo.png" width="100" alt="OpenDC">
</a>
<br>
odcsim
</h1>
<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>
<a href="https://opensource.org/licenses/MIT">
<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License">
</a>
</p>
## 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'
```
**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>
```
### 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()
}
```
### 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()
```
## 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).
|
