s4paneum / sim4da

A Simulator for Distributed Algorithms

sim4da - Simulator for Distributed Algorithms

The simulator strives to abstract from most of the details in network programming and to ease the development of algorithm simulations. The simulator core is self-contained in a Java module dev.oxoo2a.sim4da.

Writing your own simulation

The distributed algorithm simulation is controlled by an instance of class Simulator:

    Simulator s = new Simulator(n_nodes);
    for (int id=0; id<n_nodes; id++) {
      Node n = new ApplicationNode(id);
      s.attachNode(id,n);
    }
    s.runSimulation(duration);

By instantiating a Simulator object, a network of n_nodes nodes is created. For each node id between [n,n_nodes) the code for the given id must be attached to the simulator. This ApplicationNode is derived from the abstract class Node which provides all the required functionailty for implementing the algorithm simulation (see below). Finally, the simulation can be executed for duration seconds.

Extending class Node enables the implementation of the intended distributed algorithm by implementing the method main:

    public void main () {
      ...
    }

Inside main, the following methods are available:

• myId: returns the id of the given node
• numberOfNodes(): returns the total number of nodes in the network
• sendUnicast(recv_id,String message): sending a raw string message to node recv_id
• sendUnicast(recv_id,Message message): sending a HashMap-like message encoded in JSON to node recv_id
• sendBroadcast(String message): sending a raw string message to all nodes (except the sender itself)
• sendBroadcast(Message message): sending a HashMap-like message encoded in JSON to all nodes (except the sender itself)
• stillSimulating(): returns true while the duration for the simulation is not exceeded
• receive(): blocks until a message is received by the node; an object of type Network.Message is returned, which stores sender_id, receiver_id, send mode (unicast or broadcast), and the payload as a string. If a Message is expected, this payload must be deserialized from JSON back into an object of type Message by calling Message.fromJson(payload).

An example implementation for a distributed algorithm simulation is available as a test case (BroadcastNode.java and SimulatorTest.java).

Building the sim4da jar

Gradle is used as the build tool. gradle build and gradle shadowJar within the root directory of the repository generate the required jar files. The fat jar contains the transitive dependencies to gson, junit and log4j2.

Logging

The simulator core can create trace files of every simulation thanks to the logging framework log4j2. A default configuration file is part of the simulator resources. The default logging configuration is similar to:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Appenders>
        <Console name="console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n" />
        </Console>

        <File name="logfile" fileName="sim4da-app.log" append="false">
            <PatternLayout pattern="%msg%n"/>
        </File>
    </Appenders>
    <Loggers>
        <Logger name="sim4da" level="trace" additivity="false">
            <AppenderRef ref="logfile"/>
        </Logger>
        <Root level="warn">
            <AppenderRef ref="console"/>
        </Root>
    </Loggers>
</Configuration>