Merge 87d492f into c71c255

.github/CONTRIBUTING.md

@@ -1,21 +1,18 @@
 ### How to contribute?
 
+All contributors are welcome!
+
 You can choose to contribute in multiple ways:
 - comment and pick up an [issue](https://github.com/danalex97/Speer/issues)
 - create a [new issue](ISSUE_TEMPLATE/feature_request.md)
-- mail me on *dan.alex97@yahoo.com* and ask for work
-- take a look at the [contributor thread](https://github.com/danalex97/Speer/issues/33)
+- mail me on dan.alex97@yahoo.com and ask for work
 
-If you are not sure how you can contribute write onto the [contributor thread](https://github.com/danalex97/Speer/issues/33).
+If you are not sure how you can contribute write in the [contributor thread](https://github.com/danalex97/Speer/issues/33).
 
-Once you finish the work on an issue, you can create a [pull request](PULL_REQUEST_TEMPLATE.md). You can use one of the templates for [bugs](ISSUE_TEMPLATE/bug_report.md) or [feature requests](ISSUE_TEMPLATE/feature_request.md).
+Once you finish the work on an issue, you can create a [pull request](PULL_REQUEST_TEMPLATE.md). Github will let you choose between the templates for [bugs](ISSUE_TEMPLATE/bug_report.md) and [feature requests](ISSUE_TEMPLATE/feature_request.md).
 
 #### What to work on?
 
 If you do not know what to implement/work on:
 - check our [issues](https://github.com/danalex97/Speer/issues)
 - check our [roadmap](../docs/roadmap.md)
-
-#### Workload
-
-We aim to split the work for the project to be **small over larger periods of times**. We aim for a mean contribution time between **2-3 hours weekly**. We aim for the contributor work onto this project to be recreational rather than stressful.

README.md

@@ -9,6 +9,31 @@ them to easily implement, simulate and study peer to peer networks.
 
 It combines event-driven simulations with cycle-based concepts and allows parallelization by taking advantage of Go’s concurrency features.
 
+## Quickstart
+
+After getting **Golang >= 1.6** and setting **$GOPTH**, install Speer via:
+```
+curl https://raw.githubusercontent.com/danalex97/Speer/master/install.sh --output speer_install.sh
+chmod +x speer_install.sh
+./speer_install.sh
+rm speer_install.sh
+```
+
+Now, you can run a simulation from a JSON configuration as follows:
+```
+speer -config=[path_to_configuration]
+```
+
+The see the options provided by `speer.go` run:
+```
+speer -h
+```
+
+You can run the default example in `examples/broadcast.go` via the command:
+```
+speer
+```
+
 ## Table of contents
 
 - [Motivation & FAQ](docs/motivation.md)
@@ -17,15 +42,10 @@ It combines event-driven simulations with cycle-based concepts and allows parall
   - [Latency](docs/latency.md)
   - [Capacity](docs/capacity.md)
   - [Optimizations](docs/optimizations.md)
-- [User guide](docs/usage.md)
-
-## Install
-```
-go get github.com/danalex97/Speer
-```
-
-Requirements:
- - **Golang >= 1.6**
+- User guide
+  - [Interfaces](docs/interfaces.md)
+  - [Examples](docs/examples.md)
+  - [Running a simulation](docs/running.md)
 
 ## How to contribute
 

config/simulation.go

@@ -71,8 +71,7 @@ func NewSimulation(config *Config) interfaces.ISimulation {
 	if !TemplateExists() {
 		CreateTemplate(config)
 
-		pwd, _ := os.Getwd()
-		src := fmt.Sprintf("%s/speer.go", pwd)
+		src := fmt.Sprintf("%s/speer.go", speer)
 
 		// run again main
 		args := []string{}

config/template.go

@@ -9,12 +9,14 @@ import (
 	"path"
 )
 
-const (
-	stubFile   = "config/stub/stub.go.tmp"
-	stubScript = "config/stub/stub.go"
+var speer = os.Getenv("GOPATH") + "/src/github.com/danalex97/Speer/"
 
-	defaultFile   = "config/stub/default.go.tmp"
-	defaultScript = "config/stub/default.go"
+var (
+	stubFile   = speer + "config/stub/stub.go.tmp"
+	stubScript = speer + "config/stub/stub.go"
+
+	defaultFile   = speer + "config/stub/default.go.tmp"
+	defaultScript = speer + "config/stub/default.go"
 )
 
 func TemplateExists() bool {

docs/architecture.md

@@ -1,24 +1,20 @@
 ## Architecture Overview
 
-[TODO]
-
 ### Layer Summary
 
 The lowermost layer is the **Structs layer** which provides the data structures
-that we use in the other packages. The core of the simulation is **an Events library** which runs the simulation using a **lazy event queue**. Over that, we distinguish 3 main packages: the latency-related packages(**Underlay, Overlay
-and Models**), the **capacity package** and the **metrics package**.
+that we use in the other packages. The core of the simulation is **an Events library** which runs the simulation using a **lazy event queue**. Over that, we distinguish 3 main packages: the latency-related packages(**Underlay and Overlay**), the **Capacity package** and the **Logs package**.
 The **Underlay** models the latencies at the network layer, providing realistic topologies.
 The **Overlay** mainly abstracts the **Underlay** particularities away by providing an interface towards via naming abstractions and packet layering. The **Overlay** represents the transport layer encapsulation.
-Finally, the **Models** module is used to represent application-level events such as a node joining the peer-to-peer network or a query being issued.
 
 ![ ](pics/arch.png)
 
 The **Capacity** package is used to model bandwidth. It seamlessly operates with the latency module to provide the network model.
 The working model follows the TCP high-level description in order to allow a
 high number of nodes to be simulated on commodity hardware.
-The **Metrics** package is a package used to monitor the simulation. Finally, at the highest level, we have the **SDK and Interfaces**
+The **Logs** package is a package used to monitor the simulation. At a higher level, we have the **SDK and Interface**
 packages which expose to the exterior the packet transport primitives and the interfaces that need to be implemented by the user.
-Moreover, the SDK provides a **simulation builder** which can be used to define and fine-tune the simulations.
+Moreover, the SDK provides a **simulation builder** which can be used to define and fine-tune the simulations. Finally, at the highest level, the **Config** package is used to simplify defining simulations via Json files.
 
 ### Module details
 

docs/examples.md

@@ -0,0 +1,56 @@
+# Examples
+
+### Examples
+
+Before running the examples, move to the installation directory of Speer:
+```
+cd $GOPATH/src/github.com/danalex97/Speer
+```
+
+We provide the following examples:
+```
+go run speer.go -config=examples/config/sink.json
+go run speer.go -config=examples/config/broadcast.json
+go run speer.go -config=examples/config/data_link.json
+```
+
+For a more complex example, check this [repository](https://github.com/danalex97/nfsTorrent).
+
+### Primitives
+
+Getting the bootstrap node id:
+```go
+id := util.Join()
+```
+
+Sending a control message:
+
+```go
+util.Transport().ControlSend(id, "message")
+```
+
+Receiving a control message:
+
+```go
+msg := <-util.Transport().ControlRecv()
+```
+
+Sending data via a link:
+
+```go
+// Creating the link
+link := util.Transport().Connect(id)
+
+// Sending the data
+link.Upload(Data{
+  Id   : "someUniqueId", // Some ID associated with the message.
+                         // The ID can be used for keeping the actual data or metadata.
+  Size : 1000, // Total data size in bits.
+})
+```
+
+Getting data from a link:
+
+```go
+data := <-link.Download()
+```

docs/interfaces.md

@@ -0,0 +1,54 @@
+# Golang SDK
+
+The current implementation provides a Golang SDK. In order to be able to use the simulator, the user can implement the **Node** interface.
+
+Each interface comes with a **Util** interface provided to the user for interacting with a simulation:
+```go
+// This interface needs to be implemented by a node.
+type Node interface {
+	// constructor interface
+	New(util NodeUtil) Node
+
+	// The general method that is just a runner.
+	OnJoin()
+
+	// A method that should be called when a node leaves the network.
+	OnLeave()
+}
+```
+
+A user needs to implement all the methods provided below to obtain a valid node to use in a simulation:
+```go
+import (
+  . "github.com/danalex97/Speer/interfaces"
+)
+
+type Example struct {
+  //[...]
+}
+
+func (s *Example) OnJoin() {
+  //[...]
+}
+
+func (s *Example) OnLeave() {
+  //[...]
+}
+
+func (s *Example) New(util Util) Node {
+  //[...]
+}
+```
+
+The `New` function is used to generate new nodes from an empty structure template. The structure `NodeUtil` provides a set of functions which `Example` can use to interact with the simulation:
+```go
+// The Util interface is provided to a node.
+type NodeUtil interface {
+	Transport() Transport // Interface used to send data to other nodes.
+
+	Id() string // The ID of the node.
+	Join() string  // The ID of another node in the network.
+
+	Time() func() int // Function that can be used to retrieve the simulation global virtual time.
+}
+```

docs/roadmap.md

@@ -5,85 +5,72 @@ The direction in which the project goes should prioritize the following concerns
  - framework usability
  - simulation accuracy
 
-*TL;DR: Check version 1.1 for the current prioritized work.*
-
-We decide to prioritize **developer support** in order to be able to acquire a bigger developer community working on Speer. Moreover, we want to acquire **framework usability** before **simulation accuracy** so that our software is usable for a winder community, including university courses. We encountered some interest from universities for using the tool in the distributed algorithms courses, hence the prioritization of framework usability.
-
-#### Workload and contribution
-
-We aim to split the work for the project to be **small over larger periods of times**. We aim for a mean contribution time between 2-3 hours weekly.
-
-We aim for the contributor work onto this project to be recreational rather than stressful. See our [contributor guidelines](../CONTRIBUTING.md) for more details.
+*TL;DR: Check version 1.2 for the current prioritized work.*
 
 The Roadmap below is not fixed and contributions for parts in letter stages can be done earlier. If as a contributor you are interested in working on a part planned later, you are free to do so and your code will be reviewed!
 
-#### Version 1.0 [current]
+#### Version 1.0 [done]
 
-Currently, the system has a few notable problems in terms of developer support and usability:
 - no configuration files for running simulations
 - no good examples
 - no main runner with specified entry point entry point
 
-#### Version 1.1 [intent: December 2018]
+#### Version 1.1 [done]
 
-We aim for this version to be **contributor friendly**:
 - clean code-base
-- support for **configuration files**
-- reviewing standards specified and established core reviewers
+- support for configuration files
+- reviewing standards specified
 - at least 2 good usage examples
 - main command line utility which allows definition of:
-  - **path for user-supplied code** (i.e. a *.go* file)
+  - path for user-supplied code (i.e. a *.go* file)
   - path for configuration file
-- setup of a **front-end for visualization** in a JS framework(e.g. [React](https://reactjs.org/) & [D3.js](https://d3js.org/))
+- setup of a front-end for visualization in a JS framework(e.g. [React](https://reactjs.org/) & [D3.js](https://d3js.org/))
 
-#### Version 1.2 [intent: March/April 2019]
+#### Version 1.2 [intent: September 2019]
 
-At this version we want to **expand our contributor base**. The main purpose of this stage is to work on **usability**:
-- **basic front-end** with visualization tools for:
+- basic front-end with visualization tools for:
   - hop count distribution
   - latency distribution
   - throughput distribution
   - network layer topology
   - transport layer topology
-- non-preemptive **Python SDK** implementation:
-  - possibility user supplied code in Python
-  - Golang examples in Python as well
-  - library wrapper and deployment for pip
-
-#### Version 2.0 [intent: September 2019]
-
-During start of version 2.0 we want to already be able to start **talks with universities for using Speer in distributed algorithms courses.**
-
-The main focus of this stage is **gathering requirements** from universities and implementing them into Speer. Things we consider are related to usability and could include:
+- progress and safety support
+- handshake support
+- failure support
+  - node failures
+  - joins and leaves
+  - lossy links
+- routing algorithms
+  - using [BGP](https://en.wikipedia.org/wiki/Border_Gateway_Protocol) together with OSPF
+  - support for dynamic latencies
+
+#### Version 1.3
+- non-preemptive Python SDK implementation:
+    - possibility user supplied code in Python
+    - Golang examples in Python as well
+    - library wrapper and deployment for pip
+- non-preemptive Rust SDK implementation
+
+#### Version 2.0
+
+During start of version 2.0 we want to support requirements by universities interested in using Speer in distributed algorithms courses. Things we consider are related to usability and could include:
 - implementing new SDKs
 - changing the front-end
 - changing the setup process
 - changing programming primitives
 
-The work planned during this period can intersect with parts planned for the next version.
-
-#### Version 2.1 [intent: End of 2019/Beginning of 2020]
+#### Version 2.1
 
-This work is mainly focused on improving the simulations themselves, in particular:
+This work is mainly focused on improving the simulations themselves. Some examples include:
 - moving flow simulations to network level(see this [paper](https://dl.acm.org/citation.cfm?id=1272986))
-- dynamic topologies(initially model failures as Possion processes)
-- dynamic workloads(model node departure and arrival)
-- node failure(model node failure - hard and soft)
-- using [BGP](https://en.wikipedia.org/wiki/Border_Gateway_Protocol) together with OSPF
-- using [B4](https://dl.acm.org/citation.cfm?id=2486019) for WANs
 - realistic topologies: by using real datasets(e.g. [Archipelago Measurement Infrastructure](http://www.caida.org/projects/ark/))
 
 Other work can be related to improving the current simulation infrastructure. Some examples are:
 - replacing the heap with O(1) lazy structures
 - parallelize the flow allocation algorithms
-- use memory mapped files to provide faster ICP for Python SDK
-
-We are open to new ideas besides the ones described above.
-
-#### Version 3.0 [intent: sometime in the distant future]
+- faster ICP for SDKs
 
-The final goal of the simulator is to allow for **large scale simulations**. This can be done by allowing deployment on multiple machines.
+#### Version 3.0
 
-The two main lines of work are:
 - infrastructure to allow deployment of multiple simulations on multiple machines(each on 1 machine)
 - infrastructure to allow deployment of a single simulation on multiple machines