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).
Every firing of the clock defines a round,
in which the hand is given to various components sequentially:
- MessageEngine: Those messages whose propagation delay is due
are delivered to their recipients.
- Nodes: Those nodes whose waiting period is due
are notified (in a random order) by a call to their onClock() method.
- Topology: If the refresh mode of the topology is set to CLOCKBASED,
then this is when wireless links and sensing relations are updated.
- Other clock listeners: all remaining listeners,
including the JTopology (if any) and your custom listeners are notified in an arbitrary order.
- 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.
- By default, the onClock() method of every node is called in
every round. However, this can be changed by calling
setClockSpeed(i) on a given node, where i is the number of
rounds that elapse in-between two calls to its onClock()
method. This should not be mistaken with a call to
setClockSpeed() on the topology itself, whose effect is to
set the real duration of the rounds.
- 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.