cEnvir Class Reference
[User interface: cEnvir and evExtension interface to Envir]

#include <cenvir.h>

List of all members.


Detailed Description

Interface to the environment (user interface) of the simulation.

cEnvir is a common facade for the Cmdenv and Tkenv user interfaces (and any other future user interface).

cEnvir has only one instance, the ev global variable.

cEnvir member functions can be rougly divided into two groups:

The implementation of cEnvir is not part of the simulation kernel, it is in a separate library (the Envir library; see src/envir). This means that customizers are free to replace the environment of the simulation as they like, by simply linking the executable with a different library.

The default (Envir library) implementation of cEnvir delegates its task to an internal "simulation application" object. Cmdenv and Tkenv inherit from the default simulation application class.

The default (src/envir) implementation of cEnvir can be customized by subclassing the classes declared in the envirext.h header (e.g. cConfiguration, cRNG, cOutputVectorManager, cOutputScalarManager), and selecting the new classes from omnetpp.ini.


Public Member Functions

Constructor, destructor.
Note that only one instance of cEnvir exists, the ev object.

 cEnvir ()
 ~cEnvir ()
Methods called from main().
void setup (int ac, char *av[])
int run ()
void shutdown ()
Methods to be called by the simulation kernel to notify the environment about events.
void objectDeleted (cObject *object)
void messageSent (cMessage *msg, cGate *directToGate=NULL)
void moduleReparented (cModule *module, cModule *oldparent)
void messageDelivered (cMessage *msg)
void breakpointHit (const char *lbl, cSimpleModule *mod)
void moduleMethodCalled (cModule *from, cModule *to, const char *method)
void moduleCreated (cModule *newmodule)
void moduleDeleted (cModule *module)
void connectionCreated (cGate *srcgate)
void connectionRemoved (cGate *srcgate)
void displayStringChanged (cGate *gate)
void displayStringChanged (cModule *submodule)
void backgroundDisplayStringChanged (cModule *parentmodule)
void undisposedObject (cObject *obj)
Methods called by the simulation kernel to access configuration settings.
std::string getParameter (int run_no, const char *parname)
bool getParameterUseDefault (int run_no, const char *parname)
bool isModuleLocal (cModule *parentmod, const char *modname, int index)
cXMLElementgetXMLDocument (const char *filename, const char *path=NULL)
unsigned extraStackForEnvir ()
cConfigurationconfig ()
Input/output methods called from simple modules or the simulation kernel.
bool isGUI ()
bool disabled ()
void bubble (cModule *mod, const char *text)
void printfmsg (const char *fmt,...)
void printf (const char *fmt="\n",...)
void puts (const char *s)
cEnvirflush ()
std::string gets (const char *prompt, const char *defaultreply=NULL)
bool gets (const char *prompt, char *buf, int len=255)
bool askYesNo (const char *msgfmt,...)
Access to RNGs.
int numRNGs ()
cRNGrng (int k)
void getRNGMappingFor (cModule *mod)
Methods for recording data from output vectors.
These are functions cOutVector internally relies on.

The behavior of these functions can be changed by plugging in a different cOutputVectorManager object into the user interface library. (Or alternatively, by reimplementing the whole cEnvir of course).

void * registerOutputVector (const char *modulename, const char *vectorname, int tuple)
void deregisterOutputVector (void *vechandle)
bool recordInOutputVector (void *vechandle, simtime_t t, double value)
bool recordInOutputVector (void *vechandle, simtime_t t, double value1, double value2)
Scalar statistics.
The method cSimpleModule::recordScalar() function internally relies on.

The behavior of this function can be changed by plugging in a different cOutputScalarManager object into the user interface library. (Or alternatively, by reimplementing the whole cEnvir of course).

void recordScalar (cModule *module, const char *name, double value)
Management of streams where snapshots can be written.
The behavior of these functions can be changed by plugging in a different cSnapshotManager object into the user interface library. (Or alternatively, by reimplementing the whole cEnvir of course).

std::ostream * getStreamForSnapshot ()
void releaseStreamForSnapshot (std::ostream *os)
Miscellaneous functions.
int argCount ()
char ** argVector ()
int getParsimProcId ()
int getParsimNumPartitions ()
unsigned long getUniqueNumber ()
bool idle ()


Constructor & Destructor Documentation

cEnvir::cEnvir  ) 
 

Constructor.

cEnvir::~cEnvir  ) 
 

Destructor.


Member Function Documentation

int cEnvir::argCount  ) 
 

Access to original command-line arguments.

char** cEnvir::argVector  ) 
 

Access to original command-line arguments.

bool cEnvir::askYesNo const char *  msgfmt,
  ...
 

Puts a yes/no question to the user.

The question itself is expected in the printf() format (format string + arguments). The true return value means yes, false means no.

void cEnvir::backgroundDisplayStringChanged cModule parentmodule  ) 
 

Notifies the environment that a module display string has been changed.

void cEnvir::breakpointHit const char *  lbl,
cSimpleModule mod
 

Notifies the environment that a simple module executed a breakpoint() call.

void cEnvir::bubble cModule mod,
const char *  text
 

In Tkenv it pops up a "bubble" over the module icon.

cConfiguration* cEnvir::config  ) 
 

Access to the configuration data (by default, omnetpp.ini).

This is provided here for the benefit of schedulers, parallel simulation algorithms and other simulation kernel extensions. Models (simple modules) should NOT directly access the configuration -- they should rely on module parameters to get input.

void cEnvir::connectionCreated cGate srcgate  ) 
 

Notifies the environment that a connection has been created using srcgate->connectTo().

void cEnvir::connectionRemoved cGate srcgate  ) 
 

Notifies the environment that a connection has been removed using srcgate->disconnect().

void cEnvir::deregisterOutputVector void *  vechandle  ) 
 

cOutVector objects must deregister themselves when they are no longer needed.

bool cEnvir::disabled  )  [inline]
 

Returns true if the simulation is running in an Express or Express-like mode where output from ev<< and ev.printf() statement is not printed or logged anywhere but discarded.

Model code may make ev<< statements conditional on this flag to save CPU cycles. For example:

     if (!ev.disabled())  ev << "Packet " << msg->name() << " received";
 

The following version may also be useful (it makes use of the fact that << binds stronger than ?:)

     define EV  ev.disabled()?ev:ev
     EV << "Packet " << msg->name() << " received";
 

void cEnvir::displayStringChanged cModule submodule  ) 
 

Notifies the environment that a module display string has been changed.

void cEnvir::displayStringChanged cGate gate  ) 
 

Notifies the environment that a connection display string (stored in the source gate) has been changed.

unsigned cEnvir::extraStackForEnvir  ) 
 

Called from cSimpleModule, it returns how much extra stack space the user interface recommends for activity() simple modules.

cEnvir& cEnvir::flush  ) 
 

Flushes the output buffer of ev.printf() and ev<< operations.

Only some user interfaces need it: it can be useful with Cmdenv which writes to the standard output, but no need for it with Tkenv which displays all output immediately anyway.

std::string cEnvir::getParameter int  run_no,
const char *  parname
 

Called by the simulation kernel (cPar) to obtain value for an input module parameter.

Returns empty string if the configuration doesn't specify a value for this parameter.

bool cEnvir::getParameterUseDefault int  run_no,
const char *  parname
 

Called by the simulation kernel (cPar) to learn whether it should use the default value for a parameter if getParameter() fails.

int cEnvir::getParsimNumPartitions  ) 
 

Returns the number of partitions when parallel simulation is active; otherwise it returns 0.

int cEnvir::getParsimProcId  ) 
 

Returns the partitionID when parallel simulation is active.

void cEnvir::getRNGMappingFor cModule mod  ) 
 

Sets up RNG mapping (which maps module-local RNG numbers to "physical" RNGs) for the given module.

bool cEnvir::gets const char *  prompt,
char *  buf,
int  len = 255
 

DEPRECATED.

Retained for compatibility only.

std::string cEnvir::gets const char *  prompt,
const char *  defaultreply = NULL
 

Interactively prompts the user to enter a string.

std::stringstream can be used to further process the input.

std::ostream* cEnvir::getStreamForSnapshot  ) 
 

Returns a stream where a snapshot can be written.

Called from cSimulation::snapshot().

unsigned long cEnvir::getUniqueNumber  ) 
 

The function underlying cSimulation::getUniqueNumber().

cXMLElement* cEnvir::getXMLDocument const char *  filename,
const char *  path = NULL
 

Resolves reference to an XML model configuration file.

First argument is the file name of the XML document. The optional second argument may contain an XPath-like expression to denote an element within the XML document. If path is not present, the root element is returned.

See documentation of cXMLElement::getElementByPath() for path syntax. There's a difference however: paths starting with "." are not accepted, and the first path component must name the root element of the document (with getElementByPath() it would match a child element of the current element). That is, a leading "/" is always assumed at the beginning of the path expression, even if it is not explicitly there.

The method throws an exception if the document cannot be found or the given path expression is invalid. Returns NULL if the element denoted by the path expression doesn't exist in the document.

The returned object tree should not be modified because cEnvir may cache the file and return the same pointer to several callers.

bool cEnvir::idle  ) 
 

May be called from the simulation while actively waiting for some external condition to occur -- for example from blocking receive in parallel simulation, or during wait in real-time simulation.

In a graphical user interface, this method may take care of display redraw and handling user interaction (including handling of the Stop button).

Normally returns false. A true value means the user wants to abort waiting (e.g. pushed the Stop button).

bool cEnvir::isGUI  )  [inline]
 

Tells if the current environment is graphical or not.

(For Tkenv it returns true, and with Cmdenv it returns false.) Simple modules can examine this flag to decide whether or not they need to bother updating display strings.

bool cEnvir::isModuleLocal cModule parentmod,
const char *  modname,
int  index
 

Used for parallel distributed simulation.

Returns true if a to-be-created module which is (or has any submodule which is) in the local partition, and false otherwise.

Note that for compound modules that contain simple modules in several partitions, this function will return true on all those partitions.

void cEnvir::messageDelivered cMessage msg  ) 
 

Notifies the environment that a message was delivered to its destination module, that is, a message arrival event occurred.

Details can be extracted from the message object itself. The user interface implementation may use the notification to animate the message on a network diagram, to write a log entry, etc.

void cEnvir::messageSent cMessage msg,
cGate directToGate = NULL
 

Notifies the environment that a message was sent.

Details can be extracted from the message object itself. The user interface implementation may use the notification to animate the message on a network diagram, to write a log entry, etc.

The second argument is non-NULL only when sendDirect() was used, and identifies the target gate that was passed to the sendDirect() call. (This information is necessary for proper animation: the target gate might belong to a compound module and be further connected, and then the message will additionally travel through a series of connections before it arrives in a simple module.)

void cEnvir::moduleCreated cModule newmodule  ) 
 

Notifies the environment that a module was created.

This method is called from cModuleType::create(), when the module has already been created but buildInside() has not been invoked yet.

void cEnvir::moduleDeleted cModule module  ) 
 

Notifies the environment that a module was (more precisely: is being) deleted.

This method is called from cModule destructor, so the "real" type (className() and everything from the actual subclass) is already lost at this point, however name(), fullName(), fullPath(), gates, parameters (everything that comes from cModule) are still valid.

If a compound module (or a module with dynamically created submodules) is deleted, one should not assume anything about the relative order moduleDeleted() is called for the module and its submodules.

void cEnvir::moduleMethodCalled cModule from,
cModule to,
const char *  method
 

Notifies the environment that one module called a member function of another module object.

This hook enables a graphical user interface animate the method call in the network diagram.

void cEnvir::moduleReparented cModule module,
cModule oldparent
 

Notifies the environment that a module changed parent.

int cEnvir::numRNGs  ) 
 

Returns the number of RNGs available for the simulation ("num-rngs=" omnetpp.ini setting).

void cEnvir::objectDeleted cObject object  ) 
 

Notifies the environment that the object no longer exists.

The user interface should close all inspector windows for the object and remove it from object lists currently displayed. cObject's destructor automatically calls this function.

void cEnvir::printf const char *  fmt = "\n",
  ...
 

Simple modules can output text into their own window through this function.

The text is expected in printf() format (format string + arguments).

It is recommended to use C++-style I/O instead of this function.

void cEnvir::printfmsg const char *  fmt,
  ...
 

Displays a message in dialog box.

This function should not be used too much by simple modules, if ever.

void cEnvir::puts const char *  s  ) 
 

DEPRECATED.

Similar to ev.printf(), but just writes out its argument string with no formatting. Use ev<< instead.

bool cEnvir::recordInOutputVector void *  vechandle,
simtime_t  t,
double  value1,
double  value2
 

This method is intended to be called by cOutVector objects to write a value pair into the output vector.

The return value is true if the data was actually recorded, and false if it was not recorded (because of filtering, etc.)

bool cEnvir::recordInOutputVector void *  vechandle,
simtime_t  t,
double  value
 

This method is intended to be called by cOutVector objects to write a value into the output vector.

The return value is true if the data was actually recorded, and false if it was not recorded (because of filtering, etc.)

void cEnvir::recordScalar cModule module,
const char *  name,
double  value
 

Records a double scalar result, in a default configuration into the scalar result file.

void* cEnvir::registerOutputVector const char *  modulename,
const char *  vectorname,
int  tuple
 

This method is intended to be called by cOutVector objects to register themselves.

The return value is a handle of type void*; this handle has to be passed to record() to identify the vector each time a value is written.

void cEnvir::releaseStreamForSnapshot std::ostream *  os  ) 
 

Releases a stream after a snapshot was written.

cRNG* cEnvir::rng int  k  ) 
 

Returns pointer to "physical" RNG k (0 <= k < numRNGs()).

int cEnvir::run  ) 
 

Called from main().

This function should encapsulate the whole functionality of running the application. The return value may be used as exit code for the simulation program.

void cEnvir::setup int  ac,
char *  av[]
 

This function is called by main() at the beginning of the program.

It receives the command-line arguments as parameters.

void cEnvir::shutdown  ) 
 

Called from main() before exiting.

void cEnvir::undisposedObject cObject obj  ) 
 

Called from module destructors, to notify the environment about objects that the user didn't delete in the module destructor.


The documentation for this class was generated from the following file:
Generated on Sat Oct 21 17:47:56 2006 for OMNeT++/OMNEST Simulation Library by  doxygen 1.4.6