TO BE UPDATE: this documentation still referes to the alpha version

Lifecycle of the topology and internal scheduling

Lifecycle of the topology

The central component in any simulation is the Topology, responsible for managing, among others, the nodes, the links, and time scheduling in the network. As such, each topology manages a timer called the Clock, which fires periodically and activates the various components of the system in a sequential order (see Notification order below).

Topologies can be created in a running state or in a stopped state, whether one wants the Clock itself to be running or not. By default (new Topology()), it is created in a running state, meaning that the simulation begins right after the creation of the topology. This behavior is appropriate most of the time. However, in some cases, one prefers setting up the entire configuration before the execution begins. This is the case, in particular, if the nodes (and/or links) are added by program during the initialization phase. In this case, indeed, we do not want the nodes to start executing before initialization is complete. This behavior can be achieved using a false argument in the topology constructor, then calling start manually once everything is set.

Once running, the topology can be paused and resumed through the pause() and resume() methods. In case these primitives need to be called from different places, possibly being unaware of each other, the calls will be consistently stacked, as illustrated on the side Diagram (credit to Sébastien Tixeuil for this idea).

Notification order

Every firing of the clock defines a round, in which the hand is given to various components sequentially:

1. MessageEngine: Those messages whose propagation delay is due are delivered to their recipients.
2. Nodes: Those nodes whose waiting period is due are notified (in a random order) by a call to their onClock() method.
3. Topology: If the refresh mode of the topology is set to CLOCKBASED, then this is when wireless links and sensing relations are updated.
4. Other clock listeners: all remaining listeners, including the JTopology (if any) and your custom listeners are notified in an arbitrary order.

Further comments

• The order between 1. and 2. guarantees that messages are delivered to a node before this node executes its onClock() method. This implies that onMessage() is always called before onClock(), and that when onClock() executes, the mailbox is up to date.
• The default message engine always delivers messages in the very next round. However, this may not be the case with other message engines, such as jbotsimx.messaging.DelayMessageEngine.
• The topology can use to different modes for refreshing wireless links and sensing relations: EVENTBASED (the default) and CLOCKBASED. In the first case, an update is performed right after any operation susceptible of impacting the relations (e.g. a node move or a change in communication range). In the second case, it is performed only after each round, while in step 3 above.
• An extra preClock() method can be used on nodes, being called before step 1, and same for postClock() after step 4.