OMNeT++ Simulation Library  6.0.3
cenvir.h
1 //==========================================================================
2 // CENVIR.H - part of
3 // OMNeT++/OMNEST
4 // Discrete System Simulation in C++
5 //
6 //==========================================================================
7 
8 /*--------------------------------------------------------------*
9  Copyright (C) 1992-2017 Andras Varga
10  Copyright (C) 2006-2017 OpenSim Ltd.
11 
12  This file is distributed WITHOUT ANY WARRANTY. See the file
13  `license' for details on this and other legal matters.
14 *--------------------------------------------------------------*/
15 
16 #ifndef __OMNETPP_CENVIR_H
17 #define __OMNETPP_CENVIR_H
18 
19 #include <sstream>
20 #include <iostream>
21 #include "simkerneldefs.h"
22 #include "simtime_t.h"
23 #include "opp_string.h"
24 #include "clistener.h" // for simsignal_t
25 #include "clifecyclelistener.h"
26 #include "ccanvas.h"
27 
28 namespace osg { class Node; }
29 
30 namespace omnetpp {
31 
32 class cObject;
33 class cOwnedObject;
34 class cLogEntry;
35 class cEvent;
36 class cMessage;
37 class cPar;
38 class cGate;
39 class cComponent;
40 class cComponentType;
41 class cModule;
42 class cSimpleModule;
43 class cStatistic;
44 class cProperty;
45 class cRNG;
46 class cXMLElement;
47 class cEnvir;
48 class cConfiguration;
49 class cConfigurationEx;
50 struct SendOptions;
51 struct ChannelResult;
52 
53 using std::endl;
54 
55 // internal macro, usage: EVCB.beginSend(...)
56 #define EVCB cSimulation::getActiveEnvir()->suppressNotifications ? (void)0 : (*cSimulation::getActiveEnvir())
57 
75 class SIM_API cEnvir
76 {
77  friend class evbuf;
78  public:
79  // Internal flag for express mode.
80  bool loggingEnabled = true;
81 
82  // Internal flag. When set to true, the simulation kernel MAY omit calling
83  // the following cEnvir methods: messageScheduled(), messageCancelled(),
84  // beginSend(), messageSendDirect(), messageSendHop(), messageSendHop(),
85  // messageSendHop(), messageDeleted(), moduleReparented(), simulationEvent(),
86  // componentMethodBegin(), moduleCreated(), moduleDeleted(), connectionCreated(),
87  // connectionDeleted(), displayStringChanged().
88  bool suppressNotifications = false; //FIXME set to true when not needed!
89 
90  // Debugging. When set, cRuntimeError constructor executes a debug trap/launches debugger
91  bool debugOnErrors = false;
92 
93  // Lifecycle listeners
94  std::vector<cISimulationLifecycleListener*> listeners;
95 
96  public:
99 
103  cEnvir() {}
104 
108  virtual ~cEnvir() {}
110 
113 
120  // note: this cannot be pure virtual, because it has to work even after ev was disposed of
121  virtual void objectDeleted(cObject *object) {}
122 
126  virtual void componentInitBegin(cComponent *component, int stage) {}
127 
135  virtual void simulationEvent(cEvent *event) = 0;
136 
141  virtual void messageScheduled(cMessage *msg) = 0;
142 
147  virtual void messageCancelled(cMessage *msg) = 0;
148 
161  virtual void beginSend(cMessage *msg, const SendOptions& options) = 0;
162 
164  virtual void messageSendDirect(cMessage *msg, cGate *toGate, const ChannelResult& result) = 0;
165 
167  virtual void messageSendHop(cMessage *msg, cGate *srcGate) = 0;
168 
170  virtual void messageSendHop(cMessage *msg, cGate *srcGate, const ChannelResult& result) = 0;
171 
173  virtual void endSend(cMessage *msg) = 0;
174 
179  virtual void messageCreated(cMessage *msg) = 0;
180 
185  virtual void messageCloned(cMessage *msg, cMessage* clone) = 0;
186 
192  virtual void messageDeleted(cMessage *msg) = 0;
193 
197  virtual void moduleReparented(cModule *module, cModule *oldparent, int oldId) = 0;
198 
205  virtual void componentMethodBegin(cComponent *from, cComponent *to, const char *methodFmt, va_list va, bool silent) = 0;
206 
211  virtual void componentMethodEnd() = 0;
212 
218  virtual void moduleCreated(cModule *newmodule) = 0;
219 
231  virtual void moduleDeleted(cModule *module) = 0;
232 
236  virtual void gateCreated(cGate *newgate) = 0;
237 
242  virtual void gateDeleted(cGate *gate) = 0;
243 
248  virtual void connectionCreated(cGate *srcgate) = 0;
249 
254  virtual void connectionDeleted(cGate *srcgate) = 0;
255 
260  virtual void displayStringChanged(cComponent *component) = 0;
261 
266  // Note: this may not be pure virtual, as it may get called even after main()
267  // exited and StaticEnv was destructed, and we do not want to get a "pure virtual
268  // method called" error
269  virtual void undisposedObject(cObject *obj) {}
271 
278  virtual const char *getCurrentEventName() { return nullptr; }
279 
284  virtual const char *getCurrentEventClassName() { return nullptr; }
285 
290  virtual cModule *getCurrentEventModule() { return nullptr; }
292 
295 
302  virtual void preconfigure(cComponent *component) = 0;
303 
310  virtual void configure(cComponent *component) = 0;
311 
316  virtual void readParameter(cPar *parameter) = 0;
317 
328  virtual bool isModuleLocal(cModule *parentmod, const char *modname, int index) = 0;
329 
352  virtual cXMLElement *getXMLDocument(const char *filename, const char *xpath=nullptr) = 0;
353 
375  virtual cXMLElement *getParsedXMLString(const char *content, const char *xpath=nullptr) = 0;
376 
390  virtual void forgetXMLDocument(const char *filename) = 0;
391 
404  virtual void forgetParsedXMLString(const char *content) = 0;
405 
415  virtual void flushXMLDocumentCache() = 0;
416 
426  virtual void flushXMLParsedContentCache() = 0;
427 
432  virtual unsigned getExtraStackForEnvir() const = 0;
433 
441  virtual cConfiguration *getConfig() = 0;
442 
448  virtual cConfigurationEx *getConfigEx();
449 
460  virtual std::string resolveResourcePath(const char *fileName, cComponentType *context=nullptr) = 0;
462 
472  virtual bool isGUI() const = 0;
473 
478  bool isLoggingEnabled() const { return loggingEnabled; }
479 
485  virtual bool isExpressMode() const = 0;
486 
491  virtual void bubble(cComponent *component, const char *text) = 0;
492 
496  virtual void log(cLogEntry *entry) = 0;
497 
502  virtual void alert(const char *msg) = 0;
503 
507  _OPP_GNU_ATTRIBUTE(format(printf, 2, 3))
508  virtual void printfmsg(const char *fmt,...);
509 
514  virtual std::string gets(const char *prompt, const char *defaultReply=nullptr) = 0;
515 
521  virtual bool askYesNo(const char *prompt) = 0;
522 
532  virtual void getImageSize(const char *imageName, double& outWidth, double& outHeight) = 0;
533 
541  virtual void getTextExtent(const cFigure::Font& font, const char *text, double& outWidth, double& outHeight, double& outAscent) = 0;
542 
554  virtual void appendToImagePath(const char *directory) = 0;
555 
579  virtual void loadImage(const char *fileName, const char *imageName=nullptr) = 0;
580 
598  virtual cFigure::Rectangle getSubmoduleBounds(const cModule *submodule) = 0;
599 
600  /*
601  * Returns the characteristic points (currently the start and end points)
602  * of the connection arrow denoted by its source gate when it is visualized
603  * in the graphical inspector of its containing compound module,
604  * or an empty vector if the connection arrow is not available. This method
605  * is the only way to access the coordinates of connection arrows.
606  * The method may unconditionally return an empty vector when the simulation
607  * is running under Cmdenv or another non-graphical user interface. It is
608  * recommended to use the front() and back() methods of std::vector for
609  * accessing the start and end points in order to be compatible with potential
610  * future OMNeT++ versions that support splines or breakpoints in the arrows.
611  *
612  * Also note that this method may return different values at different
613  * times, e.g. as a result of the user opening and closing inspectors,
614  * hitting the "Relayout" button, or even changing the zoom level or icon
615  * size of graphical module inspectors displaying the parent module.
616  * Visualization code relying on this method is advised to re-read
617  * coordinates in every refreshDisplay() call, and check whether they
618  * changed since last time.
619  */
620  virtual std::vector<cFigure::Point> getConnectionLine(const cGate *sourceGate) = 0;
621 
636  virtual double getZoomLevel(const cModule *module) = 0;
637 
644  virtual double getAnimationTime() const = 0;
645 
655  virtual double getAnimationSpeed() const = 0;
656 
664  virtual double getRemainingAnimationHoldTime() const = 0;
666 
669 
674  virtual int getNumRNGs() const = 0;
675 
679  virtual cRNG *getRNG(int k) = 0;
681 
691 
699  virtual void *registerOutputVector(const char *modulename, const char *vectorname) = 0;
700 
704  virtual void deregisterOutputVector(void *vechandle) = 0;
705 
709  virtual void setVectorAttribute(void *vechandle, const char *name, const char *value) = 0;
710 
716  virtual bool recordInOutputVector(void *vechandle, simtime_t t, double value) = 0;
718 
728 
732  virtual void recordScalar(cComponent *component, const char *name, double value, opp_string_map *attributes=nullptr) = 0;
733 
738  virtual void recordStatistic(cComponent *component, const char *name, cStatistic *statistic, opp_string_map *attributes=nullptr) = 0;
739 
743  virtual void recordParameter(cPar *par) = 0;
744 
748  virtual void recordComponentType(cComponent *component) = 0;
750 
753 
774  virtual void addResultRecorders(cComponent *component, simsignal_t signal, const char *statisticName, cProperty *statisticTemplateProperty) = 0;
776 
784 
788  virtual std::ostream *getStreamForSnapshot() = 0;
789 
793  virtual void releaseStreamForSnapshot(std::ostream *os) = 0;
795 
801  virtual int getArgCount() const = 0;
802 
806  virtual char **getArgVector() const = 0;
807 
811  virtual int getParsimProcId() const = 0;
812 
817  virtual int getParsimNumPartitions() const = 0;
818 
822  virtual unsigned long getUniqueNumber() = 0;
823 
828  virtual void refOsgNode(osg::Node *scene) = 0;
829 
834  virtual void unrefOsgNode(osg::Node *scene) = 0;
835 
849  virtual bool idle() = 0;
850 
858  virtual void pausePoint() = 0;
859 
874  virtual bool ensureDebugger(cRuntimeError *error = nullptr) = 0;
875 
877 
885  virtual void addLifecycleListener(cISimulationLifecycleListener *listener);
886 
891  virtual void removeLifecycleListener(cISimulationLifecycleListener *listener);
892 
896  virtual std::vector<cISimulationLifecycleListener*> getLifecycleListeners() const;
897 
901  virtual void notifyLifecycleListeners(SimulationLifecycleEventType eventType, cObject *details=nullptr);
903 };
904 
905 
912 class SIM_API cRunnableEnvir : public cEnvir
913 {
914  public:
919  virtual int run(int argc, char *argv[], cConfiguration *cfg) = 0;
920 };
921 
922 } // namespace omnetpp
923 
924 #endif
925 
926 
omnetpp::cModule
This class represents modules in the simulation.
Definition: cmodule.h:48
omnetpp::ChannelResult
Allows returning multiple values from the processMessage() method.
Definition: cchannel.h:33
omnetpp::simsignal_t
int simsignal_t
Signal handle.
Definition: clistener.h:27
omnetpp::cEnvir::cEnvir
cEnvir()
Definition: cenvir.h:103
omnetpp::cConfigurationEx
Represents a configuration suitable for use with the Envir library.
Definition: cconfiguration.h:304
omnetpp::cObject
cObject is a lightweight class which serves as the root of the OMNeT++ class hierarchy....
Definition: cobject.h:92
omnetpp::cConfiguration
Represents the configuration, as accessed by the simulation kernel.
Definition: cconfiguration.h:76
omnetpp::cEvent
Represents an event in the discrete event simulator.
Definition: cevent.h:46
omnetpp::cLogEntry
This class holds various data that is captured when a particular log statement executes....
Definition: clog.h:376
omnetpp::opp_string_map
Lightweight string-to-string map, used internally in some parts of OMNeT++.
Definition: opp_string.h:219
omnetpp::SimulationLifecycleEventType
SimulationLifecycleEventType
Event type for cISimulationLifecycleListener's lifecycleEvent() method.
Definition: clifecyclelistener.h:28
omnetpp::cEnvir::getCurrentEventModule
virtual cModule * getCurrentEventModule()
Definition: cenvir.h:290
omnetpp::SimTime
int64_t-based, base-10 fixed-point simulation time.
Definition: simtime.h:66
omnetpp::cEnvir::componentInitBegin
virtual void componentInitBegin(cComponent *component, int stage)
Definition: cenvir.h:126
omnetpp::cEnvir::getCurrentEventClassName
virtual const char * getCurrentEventClassName()
Definition: cenvir.h:284
omnetpp::SendOptions
Options for the cSimpleModule::send() and cSimpleModule::sendDirect() calls.
Definition: csimplemodule.h:82
omnetpp::cEnvir::~cEnvir
virtual ~cEnvir()
Definition: cenvir.h:108
omnetpp::cEnvir::undisposedObject
virtual void undisposedObject(cObject *obj)
Definition: cenvir.h:269
omnetpp::cGate
Represents a module gate.
Definition: cgate.h:62
omnetpp::cRNG
Abstract interface for random number generator classes.
Definition: crng.h:48
omnetpp::cPar
Represents a module or channel parameter.
Definition: cpar.h:70
omnetpp::cEnvir::objectDeleted
virtual void objectDeleted(cObject *object)
Definition: cenvir.h:121
omnetpp::cComponentType
Common base class for cModuleType and cChannelType.
Definition: ccomponenttype.h:49
omnetpp::cMessage
The message class in OMNeT++. cMessage objects may represent events, messages, jobs or other entities...
Definition: cmessage.h:95
omnetpp::cXMLElement
Represents an XML element in an XML configuration file.
Definition: cxmlelement.h:75
omnetpp::cComponent
Common base for module and channel classes.
Definition: ccomponent.h:49
omnetpp::cEnvir::getCurrentEventName
virtual const char * getCurrentEventName()
Definition: cenvir.h:278
omnetpp::cStatistic
cStatistic is an abstract class for computing statistical properties of a random variable.
Definition: cstatistic.h:34
omnetpp::cEnvir::isLoggingEnabled
bool isLoggingEnabled() const
Definition: cenvir.h:478
omnetpp::cRuntimeError
Thrown when the simulation kernel or other components detect a runtime error.
Definition: cexception.h:286
omnetpp::cEnvir
cEnvir represents the "environment" or user interface of the simulation.
Definition: cenvir.h:75
omnetpp::cProperty
Stores a (NED) property with its (possibly compound) value.
Definition: cproperty.h:38
omnetpp::cISimulationLifecycleListener
A callback interface for receiving notifications at various stages simulations, including setting up,...
Definition: clifecyclelistener.h:186
omnetpp::cFigure
A lightweight graphical object for cCanvas.
Definition: ccanvas.h:60
omnetpp::cRunnableEnvir
A cEnvir that can be instantiated as a user interface, like Cmdenv and Tkenv.
Definition: cenvir.h:912