Signals in OMNeT++ Andr á s Varga OMNeT++ Workshop March 19, 2010 Malaga, Spain

1. Signals in OMNeT++ András Varga OMNeT++ Workshop March 19, 2010 Malaga, Spain

2. Motivation Problems to solve: • Need more flexible statistics recording • Ideally, module should just produce the values, and we want to be able to decide per-run basis what to record and how (vector, mean/stddev, histogram, etc.) • Existing models: they need to calculate and output “everything”, and actual recording may be disabled via configuration options • Support for global statistics processing modules • Example: watch for the total #drops in the network to raise over a limit, and tune model parameters accordingly • Currently not possible without changing participating modules

3. Motivation / 2 In the INET Framework: • Support for exposing pcap traces • We need to be able to record packet traces easily, without obtrusive changes to existing models: • without inserting an extra submodule deep inside StandardHost • without adding fwrite() calls and “string pcapFileName” parameters into L2 modules • Support for creating global log files • E.g. “nam” traces, whose contents should come from all over the simulation • Model change notification • Certain model components need to get informed about runtime topology changes • For example, the PPP module needs to update internal cached channel pointer when it gets reconnected

4. Idea Recurrent element: • Producer of information needs to be decoupled from consumer. Why not build a publish-subscribemechanism into OMNeT++ itself? Note: there is MF’s Blackboard and INET’s NotificationBoard, but they are not suitable for many of these tasks (e.g. statistics, model change notification)

5. The Signals API Component (module or channel) class: • emit(signal, long) • emit(signal, double) • emit(signal, simtime_t) • emit(signal, const char *) • emit(signal, cObject *)  for everything else Listener (cIListener class): • receiveSignal(sourceComponent, signal, long) • receiveSignal(sourceComponent, signal, double) • receiveSignal(sourceComponent, signal, simtime_t) • receiveSignal(sourceComponent, signal, const char *) • receiveSignal(sourceComponent, signal, cObject *) • +1: finish(component, signal)  mostly for result recording

6. Adding Listeners Component (module or channel) class: • subscribe(signal, cIListener *) • unsubscribe(signal, cIListener *) • hasListeners(signal) Listener (cIListener): • subscribedTo(component, signal) • unsubscribedFrom(component, signal)

7. Signal Propagation Signals propagate up the module tree: • You can subscribe at the module, or at any ancestor • Listeners subscribed at the root are catch-alls • Optimization: no listener – no notification overhead! Practical examples: • INET’s NotificationBoard can be substituted by adding listeners to the host compound module • Facilitates collecting global or aggregated statistics • if statistics are exposed as signals, aggregation can be done by adding listeners at the root module

8. Identifying Signals • Signals are identified by name (a string) • During simulation: simsignal_t • dynamically assigned numeric identifier, used for efficiency reasons; “signal ID” • Obtaining the signal ID from signal name: cComponent::registerSignal(“signalname”); • Signal names and signal IDs are global • Different modules “registering” (looking up) the same name get the same signal ID

9. NotificationBoard Signals as replacement for INET’s NotificationBoard • How? • Modules emit notifications as (local) signals • Listeners subscribe at the host/router compound module • Why? • Efficiency: signal allow emitting only when needed • Notification information may be costly to produce, and maybe no one is listening! Signals have an efficient hasListeners() method. • Uniformity: • Signals emitted this way may be used for other purposes as well, e.g. for statistics recording (e.g. “number of routing table changes during simulation”)

10. Signals Currently signals are ready to be used for: • Model change notifications • Statistics recording • Model-specific use (e.g. as NotificationBoard) Planned: • pcap trace recording, nam trace recording • As input for custom animations • To be used by a future animation framework. Examples: wireless transmission effects; visualize routes discovered by routing protocols

11. Model Change Notifications • Two predefined signals: • PRE_MODEL_CHANGE, POST_MODEL_CHANGE • Notifications are emitted as objects • subclassed from cModelChangeNotification • contain the details about the change

12. Model Change Notifications Notification details data classes:

13. Model Change Notifications Example notification details classes: class cPostGateVectorResizeNotification : ... { cModule *module; const char *gateName; int oldSize; }; class cPostGateConnectNotification : … { cGate *gate; }; class cPre/PostPathCreateNotification : … {  same for xxxPathCutNotification cGate *pathStartGate; cGate *pathEndGate; cGate *changedGate;  the gate that got connected or disconnected };

14. Planned: Packet Trace Recording Recording pcap traces: • Modules emit packets as signal value (cPacket*) • The simulation framework may subscribe to the signal • Listener converts packets to byte arrays and records them into a pcap file • Crucial: pcap-recording listener should be extensible • Tkenv support (“Save pcap trace…” menu item)

15. Statistics Recording Statistics recording using signals: • Data are emitted as signals from modules/channels • emit(signalID, x) • Statistics are declared in the NED files • @statistic property • may define: name, title, interpolation mode, unit, default recording mode (as vector, as histogram, etc) • Configurability: • amount of information to be recorded can be changed from omnetpp.ini • Compatibility: • This is just a layer above existing vectors/scalars

16. Statistics Basic syntax: @statistic[name](attr1=value1;attr2=value2;…); • Statistic name is also the signal name (by default) • Attributes get recorded to the result files • Some attribute names: • title: text for chart legend • unit: unit of measurement (for display on charts) • interpolationmode: linear, sample-hold, backward-sample-hold, none (affects chart drawing)

17. Statistics: An Example NED example: simple Fifo { parameters: volatile double serviceTime @unit(s); @statistic[queueLen](title="queue length”; interpolationmode=sample-hold); @statistic[busy](interpolationmode=sample-hold); @statistic[queueingTime](unit=s); gates: input in; output out; }

18. Statistics • Recording mode: • @statistic[qlen](record=vector,max,timeavg); • Available recorders: • last, mean, timeavg, min, max, sum, count, histogram, vector • new ones can be defined • Recording mode can be modified from omnetpp.ini: • **.qlen.result-recoding-mode = +count,-vector

19. Statistics When statistic name and signal name differ: • @statistic[queueLength](source=qlen; record=vector,max,timeavg); Object-to-number transformations: • @statistic[numTxPks](source=“count(txStart)”; record=vector,last); • @statistic[txBytes](source=“pkBytes(txStart)”; record=vector,histogram); Expressions: • @statistic[txBits](source=“8*pkBytes(txStart)”; record=vector,histogram); • @statistic[txPksCum](source=“constant1(txStart)”;record=vector(sum));

20. Statistics Recording with timestamp: • Must be emitted as object (cObject*) • Helper class: cTimestampedValue • contains a timestamp and a value • Usage: cTimestampedValue tmp(timestamp, value); emit(signalID, &tmp);

21. Statistics: Extensibility Defining new result filters and result recorders • To list existing ones: $ ./mysim -h resultfilters $ ./mysim -h resultrecorders • To add existing ones: • Implement ResultFilter / ResultRecorder (from src/envir) • Register them with the Register_ResultFilter() and Register_ResultRecorder() macros

22. Statistics: Example Recorder class MeanRecorder : public NumericResultRecorder { protected: long count; double sum; protected: virtual void collect(double value) {count++; sum += value;} virtual void collect(simtime_t t, double value) {count++; sum += value;} public: MeanRecorder() {count = 0; sum = 0;} virtual void finish(ResultFilter *prev) { opp_string_map attributes = getStatisticAttributes(); ev.recordScalar(getComponent(), getResultName().c_str(), sum/count, &attributes); } }; Register_ResultRecorder(“mean”, MeanRecorder);

23. Conclusion • A new Signals framework has been introduced in OMNeT++ • Purposes: • Publish-subscribe communication in the model • Statistics collection and recording • Model change notification • Trace file writing (pcap, nam) • Other

24. Signals Questions, comments? Discussion