cenvir.h

//==========================================================================
//  CENVIR.H - part of
//
//                     OMNeT++/OMNEST
//            Discrete System Simulation in C++
//
//==========================================================================

/*--------------------------------------------------------------*
  Copyright (C) 1992-2008 Andras Varga
  Copyright (C) 2006-2008 OpenSim Ltd.

  This file is distributed WITHOUT ANY WARRANTY. See the file
  `license' for details on this and other legal matters.
*--------------------------------------------------------------*/

#ifndef __CENVIR_H
#define __CENVIR_H

#include <sstream>
#include <iostream>
#include "simkerneldefs.h"
#include "simtime_t.h"
#include "opp_string.h"
#include "csimulation.h"
#include "clistener.h"  // for simsignal_t

NAMESPACE_BEGIN

class cObject;
class cOwnedObject;
class cMessage;
class cPar;
class cGate;
class cComponent;
class cModule;
class cSimpleModule;
class cStatistic;
class cProperty;
class cRNG;
class cXMLElement;
class cEnvir;
class cConfiguration;
class cConfigurationEx;

using std::endl;

// internal macro, usage: EVCB.beginSend(...)
#define EVCB  ev.suppress_notifications ? (void)0 : ev

#define ev  (*cSimulation::getActiveEnvir())


#define EV  ev.isDisabled()?ev:ev   /*Note: deliberately NO parens*/


class SIM_API cEnvir
{
    friend class evbuf;
  public:
    // Internal flag for express mode.
    bool disable_tracing;

    // Indicates whether eventlog recording is currently enabled
    bool record_eventlog;

    // 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 suppress_notifications;

    // Internal flags. When set, cRuntimeError constructor executes a debug trap/launches debugger
    bool debug_on_errors;
    bool attach_debugger_on_errors;

  protected:
    // further internal vars
    std::ostream out;

  protected:
    // internal: ev.printf() and ev<< eventually ends up here; write the first n characters of string s
    virtual void sputn(const char *s, int n) = 0;

    // internal: pop up a dialog with the given message; called from printfmsg()
    virtual void putsmsg(const char *msg) = 0;

    // internal: ask a yes/no question, throws exception if cancelled; askYesNo() delegates here
    virtual bool askyesno(const char *msg) = 0;

    // internal: flushes the internal stream buffer by terminating last line if needed
    void flushLastLine();

  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(cMessage *msg) = 0;

    virtual void messageSent_OBSOLETE(cMessage *msg, cGate *directToGate=NULL) = 0;

    virtual void messageScheduled(cMessage *msg) = 0;

    virtual void messageCancelled(cMessage *msg) = 0;

    virtual void beginSend(cMessage *msg) = 0;

    virtual void messageSendDirect(cMessage *msg, cGate *toGate, simtime_t propagationDelay, simtime_t transmissionDelay) = 0;

    virtual void messageSendHop(cMessage *msg, cGate *srcGate) = 0;

    virtual void messageSendHop(cMessage *msg, cGate *srcGate, simtime_t propagationDelay, simtime_t transmissionDelay) = 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) = 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 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=NULL) = 0;

    virtual cXMLElement *getParsedXMLString(const char *content, const char *xpath=NULL) = 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 bool isGUI() const = 0;

    bool isDisabled() const {return disable_tracing && !record_eventlog;}

    // implementation note: needed because otherwise the templated version
    // would cause ambiguity errors in some cases
    cEnvir& operator<<(const std::string& t) {out << t; return *this;}

    template<typename T> cEnvir& operator<<(const T& t) {out << t; return *this;}

    cEnvir& operator<<(std::ostream& (t)(std::ostream&)) {out << t; return *this;}

    std::ostream& getOStream() {return out;}

    virtual void bubble(cComponent *component, const char *text) = 0;

    virtual void printfmsg(const char *fmt,...);

    // note: non-virtual, delegates to sputn()
    virtual int printf(const char *fmt,...);

    virtual cEnvir& flush() = 0;

    virtual std::string gets(const char *prompt, const char *defaultreply=NULL) = 0;

    // note: non-virtual, delegates to askyesno()
    virtual bool askYesNo(const char *fmt,...);


    virtual int getNumRNGs() const = 0;

    virtual cRNG *getRNG(int k) = 0;

    virtual void getRNGMappingFor(cComponent *component) = 0;


    virtual void *registerOutputVector(const char *modulename, const char *vectorname) = 0;

    virtual void deregisterOutputVector(void *vechandle) = 0;

    virtual void setVectorAttribute(void *vechandle, const char *name, const char *value) = 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=NULL) = 0;

    virtual void recordStatistic(cComponent *component, const char *name, cStatistic *statistic, opp_string_map *attributes=NULL) = 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 bool idle() = 0;

    virtual void attachDebugger() = 0;
};


class SIM_API cRunnableEnvir : public cEnvir
{
  public:
    virtual int run(int argc, char *argv[], cConfiguration *cfg) = 0;
};

NAMESPACE_END

#endif