cenvir.h

//==========================================================================
//  CENVIR.H - part of
//                     OMNeT++/OMNEST
//            Discrete System Simulation in C++
//
//==========================================================================
 
/*--------------------------------------------------------------*
  Copyright (C) 1992-2017 Andras Varga
  Copyright (C) 2006-2017 OpenSim Ltd.
 
  This file is distributed WITHOUT ANY WARRANTY. See the file
  `license' for details on this and other legal matters.
*--------------------------------------------------------------*/
 
#ifndef __OMNETPP_CENVIR_H
#define __OMNETPP_CENVIR_H
 
#include <sstream>
#include <iostream>
#include "simkerneldefs.h"
#include "simtime_t.h"
#include "opp_string.h"
#include "clistener.h"  // for simsignal_t
#include "clifecyclelistener.h"
#include "ccanvas.h"
 
namespace osg { class Node; }
 
namespace omnetpp {
 
class cObject;
class cOwnedObject;
class cLogEntry;
class cEvent;
class cMessage;
class cPar;
class cGate;
class cComponent;
class cComponentType;
class cModule;
class cSimpleModule;
class cStatistic;
class cProperty;
class cRNG;
class cXMLElement;
class cEnvir;
class cConfiguration;
class cConfigurationEx;
struct SendOptions;
struct ChannelResult;
 
using std::endl;
 
// internal macro, usage: EVCB.beginSend(...)
#define EVCB  cSimulation::getActiveEnvir()->suppressNotifications ? (void)0 : (*cSimulation::getActiveEnvir())
 
class SIM_API cEnvir
{
    friend class evbuf;
  public:
    // Internal flag for express mode.
    bool loggingEnabled = true;
 
    // Internal flag. When set to true, the simulation kernel MAY omit calling
    // the following cEnvir methods: messageScheduled(), messageCancelled(),
    // beginSend(), messageSendDirect(), messageSendHop(), messageSendHop(),
    // messageSendHop(), messageDeleted(), moduleReparented(), simulationEvent(),
    // componentMethodBegin(), moduleCreated(), moduleDeleted(), connectionCreated(),
    // connectionDeleted(), displayStringChanged().
    bool suppressNotifications = false; //FIXME set to true when not needed!
 
    // Debugging. When set, cRuntimeError constructor executes a debug trap/launches debugger
    bool debugOnErrors = false;
 
    // Lifecycle listeners
    std::vector<cISimulationLifecycleListener*> listeners;
 
  public:
 
    cEnvir() {}
 
    virtual ~cEnvir() {}
 
 
    // note: this cannot be pure virtual, because it has to work even after ev was disposed of
    virtual void objectDeleted(cObject *object) {}
 
    virtual void componentInitBegin(cComponent *component, int stage) {}
 
    virtual void simulationEvent(cEvent *event) = 0;
 
    virtual void messageScheduled(cMessage *msg) = 0;
 
    virtual void messageCancelled(cMessage *msg) = 0;
 
    virtual void beginSend(cMessage *msg, const SendOptions& options) = 0;
 
    virtual void messageSendDirect(cMessage *msg, cGate *toGate, const ChannelResult& result) = 0;
 
    virtual void messageSendHop(cMessage *msg, cGate *srcGate) = 0;
 
    virtual void messageSendHop(cMessage *msg, cGate *srcGate, const ChannelResult& result) = 0;
 
    virtual void endSend(cMessage *msg) = 0;
 
    virtual void messageCreated(cMessage *msg) = 0;
 
    virtual void messageCloned(cMessage *msg, cMessage* clone) = 0;
 
    virtual void messageDeleted(cMessage *msg) = 0;
 
    virtual void moduleReparented(cModule *module, cModule *oldparent, int oldId) = 0;
 
    virtual void componentMethodBegin(cComponent *from, cComponent *to, const char *methodFmt, va_list va, bool silent) = 0;
 
    virtual void componentMethodEnd() = 0;
 
    virtual void moduleCreated(cModule *newmodule) = 0;
 
    virtual void moduleDeleted(cModule *module) = 0;
 
    virtual void gateCreated(cGate *newgate) = 0;
 
    virtual void gateDeleted(cGate *gate) = 0;
 
    virtual void connectionCreated(cGate *srcgate) = 0;
 
    virtual void connectionDeleted(cGate *srcgate) = 0;
 
    virtual void displayStringChanged(cComponent *component) = 0;
 
    // Note: this may not be pure virtual, as it may get called even after main()
    // exited and StaticEnv was destructed, and we do not want to get a "pure virtual
    // method called" error
    virtual void undisposedObject(cObject *obj) {}
 
    virtual const char *getCurrentEventName() { return nullptr; }
 
    virtual const char *getCurrentEventClassName() { return nullptr; }
 
    virtual cModule *getCurrentEventModule() { return nullptr; }
 
 
    virtual void preconfigure(cComponent *component) = 0;
 
    virtual void configure(cComponent *component) = 0;
 
    virtual void readParameter(cPar *parameter) = 0;
 
    virtual bool isModuleLocal(cModule *parentmod, const char *modname, int index) = 0;
 
    virtual cXMLElement *getXMLDocument(const char *filename, const char *xpath=nullptr) = 0;
 
    virtual cXMLElement *getParsedXMLString(const char *content, const char *xpath=nullptr) = 0;
 
    virtual void forgetXMLDocument(const char *filename) = 0;
 
    virtual void forgetParsedXMLString(const char *content) = 0;
 
    virtual void flushXMLDocumentCache() = 0;
 
    virtual void flushXMLParsedContentCache() = 0;
 
    virtual unsigned getExtraStackForEnvir() const = 0;
 
    virtual cConfiguration *getConfig() = 0;
 
    virtual cConfigurationEx *getConfigEx();
 
    virtual std::string resolveResourcePath(const char *fileName, cComponentType *context=nullptr) = 0;
 
    virtual bool isGUI() const = 0;
 
    bool isLoggingEnabled() const { return loggingEnabled; }
 
    virtual bool isExpressMode() const = 0;
 
    virtual void bubble(cComponent *component, const char *text) = 0;
 
    virtual void log(cLogEntry *entry) = 0;
 
    virtual void alert(const char *msg) = 0;
 
    _OPP_GNU_ATTRIBUTE(format(printf, 2, 3))
    virtual void printfmsg(const char *fmt,...);
 
    virtual std::string gets(const char *prompt, const char *defaultReply=nullptr) = 0;
 
    virtual bool askYesNo(const char *prompt) = 0;
 
    virtual std::ostream& getOutputStream() = 0;
 
    virtual void getImageSize(const char *imageName, double& outWidth, double& outHeight) = 0;
 
    virtual void getTextExtent(const cFigure::Font& font, const char *text, double& outWidth, double& outHeight, double& outAscent) = 0;
 
    virtual void appendToImagePath(const char *directory) = 0;
 
    virtual void loadImage(const char *fileName, const char *imageName=nullptr) = 0;
 
    virtual cFigure::Rectangle getSubmoduleBounds(const cModule *submodule) = 0;
 
    /*
     * Returns the characteristic points (currently the start and end points)
     * of the connection arrow denoted by its source gate when it is visualized
     * in the graphical inspector of its containing compound module,
     * or an empty vector if the connection arrow is not available. This method
     * is the only way to access the coordinates of connection arrows.
     * The method may unconditionally return an empty vector when the simulation
     * is running under Cmdenv or another non-graphical user interface. It is
     * recommended to use the front() and back() methods of std::vector for
     * accessing the start and end points in order to be compatible with potential
     * future OMNeT++ versions that support splines or breakpoints in the arrows.
     *
     * Also note that this method may return different values at different
     * times, e.g. as a result of the user opening and closing inspectors,
     * hitting the "Relayout" button, or even changing the zoom level or icon
     * size of graphical module inspectors displaying the parent module.
     * Visualization code relying on this method is advised to re-read
     * coordinates in every refreshDisplay() call, and check whether they
     * changed since last time.
     */
    virtual std::vector<cFigure::Point> getConnectionLine(const cGate *sourceGate) = 0;
 
    virtual double getZoomLevel(const cModule *module) = 0;
 
    virtual double getAnimationTime() const = 0;
 
    virtual double getAnimationSpeed() const = 0;
 
    virtual double getRemainingAnimationHoldTime() const = 0;
 
 
    virtual int getNumRNGs() const = 0;
 
    virtual cRNG *getRNG(int k) = 0;
 
 
    virtual void *registerOutputVector(const char *modulename, const char *vectorname, opp_string_map *attributes=nullptr) = 0;
 
    virtual void deregisterOutputVector(void *vechandle) = 0;
 
    virtual bool recordInOutputVector(void *vechandle, simtime_t t, double value) = 0;
 
 
    virtual void recordScalar(cComponent *component, const char *name, double value, opp_string_map *attributes=nullptr) = 0;
 
    virtual void recordStatistic(cComponent *component, const char *name, cStatistic *statistic, opp_string_map *attributes=nullptr) = 0;
 
    virtual void recordParameter(cPar *par) = 0;
 
    virtual void recordComponentType(cComponent *component) = 0;
 
 
    virtual void addResultRecorders(cComponent *component, simsignal_t signal, const char *statisticName, cProperty *statisticTemplateProperty) = 0;
 
 
    virtual std::ostream *getStreamForSnapshot() = 0;
 
    virtual void releaseStreamForSnapshot(std::ostream *os) = 0;
 
    virtual int getArgCount() const = 0;
 
    virtual char **getArgVector() const = 0;
 
    virtual int getParsimProcId() const = 0;
 
    virtual int getParsimNumPartitions() const = 0;
 
    virtual unsigned long getUniqueNumber() = 0;
 
    virtual void refOsgNode(osg::Node *scene) = 0;
 
    virtual void unrefOsgNode(osg::Node *scene) = 0;
 
    virtual bool idle() = 0;
 
    virtual void pausePoint() = 0;
 
    virtual bool ensureDebugger(cRuntimeError *error = nullptr) = 0;
 
 
    virtual void addLifecycleListener(cISimulationLifecycleListener *listener);
 
    virtual void removeLifecycleListener(cISimulationLifecycleListener *listener);
 
    virtual std::vector<cISimulationLifecycleListener*> getLifecycleListeners() const;
 
    virtual void notifyLifecycleListeners(SimulationLifecycleEventType eventType, cObject *details=nullptr);
};
 
 
class SIM_API cRunnableEnvir : public cEnvir
{
  public:
    virtual int run(int argc, char *argv[], cConfiguration *cfg) = 0;
};
 
}  // namespace omnetpp
 
#endif