OMNeT++ Simulation Library  6.0.3
cSimulation Class Reference

#include <csimulation.h>

Description

Simulation manager class.

cSimulation is the central class in OMNeT++. It stores the active simulation model, and provides methods for setting up, running and finalizing simulations.

Most cSimulation methods are not of interest for simulation model code, they are used internally (e.g. by the user interface libraries (Envir, Cmdenv, Qtenv) to set up and run simulations).

Some methods which can be of interest when programming simple modules: getUniqueNumber(), getModuleByPath(), getModule(), snapshot().

Inheritance diagram for cSimulation:
cNamedObject noncopyable cObject

Public Member Functions

Constructor, destructor.
 cSimulation (const char *name, cEnvir *env)
 
virtual ~cSimulation ()
 
Redefined cObject member functions.
virtual void forEachChild (cVisitor *v) override
 
virtual std::string getFullPath () const override
 
Accessing modules.
int registerComponent (cComponent *component)
 
void deregisterComponent (cComponent *component)
 
int getLastComponentId () const
 
cModulegetModuleByPath (const char *modulePath) const
 
cModulefindModuleByPath (const char *modulePath) const
 
cComponentgetComponent (int id) const
 
cModulegetModule (int id) const
 
cChannelgetChannel (int id) const
 
void setSystemModule (cModule *module)
 
cModulegetSystemModule () const
 
Setting up and finishing a simulation run.
void setScheduler (cScheduler *scheduler)
 
cSchedulergetScheduler () const
 
void setFES (cFutureEventSet *fes)
 
cFutureEventSetgetFES () const
 
void setSimulationTimeLimit (simtime_t simTimeLimit)
 
void setupNetwork (cModuleType *networkType)
 
void callInitialize ()
 
void callFinish ()
 
void deleteNetwork ()
 
Information about the current simulation run.
int getSimulationStage () const
 
cModuleTypegetNetworkType () const
 
void setSimTime (simtime_t time)
 
simtime_t_cref getSimTime () const
 
eventnumber_t getEventNumber () const
 
simtime_t_cref getWarmupPeriod () const
 
void setWarmupPeriod (simtime_t t)
 
Scheduling and simulation execution.
cEventguessNextEvent ()
 
cSimpleModuleguessNextModule ()
 
simtime_t guessNextSimtime ()
 
cEventtakeNextEvent ()
 
void putBackEvent (cEvent *event)
 
void executeEvent (cEvent *event)
 
void callRefreshDisplay ()
 
void transferTo (cSimpleModule *module)
 
void transferToMain ()
 
void insertEvent (cEvent *event)
 
void setContext (cComponent *component)
 
void setContextType (ContextType type)
 
void setGlobalContext ()
 
cSimpleModulegetActivityModule () const
 
cComponentgetContext () const
 
ContextType getContextType () const
 
cModulegetContextModule () const
 
cSimpleModulegetContextSimpleModule () const
 
void requestTrapOnNextEvent ()
 
void clearTrapOnNextEvent ()
 
bool isTrapOnNextEventRequested () const
 
Miscellaneous.
unsigned long getUniqueNumber ()
 
void snapshot (cObject *obj, const char *label)
 
cFingerprintCalculatorgetFingerprintCalculator ()
 
void setFingerprintCalculator (cFingerprintCalculator *fingerprint)
 
- Public Member Functions inherited from cNamedObject
 cNamedObject ()
 
 cNamedObject (const char *name, bool namepooling=true)
 
 cNamedObject (const cNamedObject &obj)
 
virtual ~cNamedObject ()
 
cNamedObjectoperator= (const cNamedObject &o)
 
virtual void parsimPack (cCommBuffer *buffer) const override
 
virtual void parsimUnpack (cCommBuffer *buffer) override
 
virtual void setName (const char *s)
 
virtual const char * getName () const override
 
virtual void setNamePooling (bool b)
 
virtual bool getNamePooling ()
 
- Public Member Functions inherited from cObject
 cObject ()
 
 cObject (const cObject &other)=default
 
virtual ~cObject ()
 
virtual const char * getClassName () const
 
bool isName (const char *s) const
 
virtual const char * getFullName () const
 
virtual std::string getClassAndFullName () const
 
virtual std::string getClassAndFullPath () const
 
const cObjectgetThisPtr () const
 
virtual std::string str () const
 
virtual std::ostream & printOn (std::ostream &os) const
 
virtual cObjectdup () const
 
virtual cObjectgetOwner () const
 
virtual bool isOwnedObject () const
 
virtual bool isSoftOwner () const
 
cObjectfindObject (const char *name, bool deep=true)
 
virtual cClassDescriptorgetDescriptor () const
 
void copyNotSupported () const
 

Static Public Member Functions

Loading NED files.

These functions delegate to the netbuilder part of the simulation kernel, and they are present so that cEnvir and other libs outside the simkernel do not need to directly depend on nedxml or netbuilder classes, and conditional compilation (#ifdef WITH_NETBUILDER) can be limited to the simkernel.

static int loadNedSourceFolder (const char *folderName, const char *excludedPackages="")
 
static void loadNedFile (const char *nedFilename, const char *expectedPackage=nullptr, bool isXML=false)
 
static void loadNedText (const char *name, const char *nedText, const char *expectedPackage=nullptr, bool isXML=false)
 
static void doneLoadingNedFiles ()
 
static std::string getNedPackageForFolder (const char *folder)
 

Accessing and switching the active simulation object

cEnvirgetEnvir () const
 
static cSimulationgetActiveSimulation ()
 
static cEnvirgetActiveEnvir ()
 
static void setActiveSimulation (cSimulation *sim)
 
static void setStaticEnvir (cEnvir *env)
 
static cEnvirgetStaticEnvir ()
 

Additional Inherited Members

- Protected Member Functions inherited from cObject
virtual void take (cOwnedObject *obj)
 
virtual void drop (cOwnedObject *obj)
 
void dropAndDelete (cOwnedObject *obj)
 

Constructor & Destructor Documentation

◆ cSimulation()

cSimulation ( const char *  name,
cEnvir env 
)

Constructor. The environment object will be associated with this simulation object, and gets deleted in the simulation object's destructor.

◆ ~cSimulation()

virtual ~cSimulation ( )
virtual

Destructor.

Member Function Documentation

◆ forEachChild()

virtual void forEachChild ( cVisitor v)
overridevirtual

Calls v->visit(this) for each contained object. See cObject for more details.

Reimplemented from cObject.

◆ getFullPath()

virtual std::string getFullPath ( ) const
overridevirtual

Redefined. (Reason: a C++ rule that overloaded virtual methods must be redefined together.)

Reimplemented from cObject.

◆ getActiveSimulation()

static cSimulation* getActiveSimulation ( )
inlinestatic

Returns the active simulation object. May be nullptr.

Referenced by omnetpp::getSimulation(), and omnetpp::simTime().

◆ getActiveEnvir()

static cEnvir* getActiveEnvir ( )
inlinestatic

Returns the environment object for the active simulation. Never returns nullptr; setActiveSimulation(nullptr) will cause a static "do-nothing" instance to step in.

Referenced by omnetpp::getEnvir().

◆ setActiveSimulation()

static void setActiveSimulation ( cSimulation sim)
static

Activate the given simulation object, and its associated environment object. nullptr is also accepted; it will cause the static environment object to step in (see getStaticEnvir()).

◆ setStaticEnvir()

static void setStaticEnvir ( cEnvir env)
static

Sets the environment object to use when there is no active simulation object. The argument cannot be nullptr.

◆ getStaticEnvir()

static cEnvir* getStaticEnvir ( )
inlinestatic

Returns the environment object to use when there is no active simulation object.

◆ getEnvir()

cEnvir* getEnvir ( ) const
inline

Returns the environment object associated with this simulation object.

◆ registerComponent()

int registerComponent ( cComponent component)

Registers the component in cSimulation and assigns it an ID. It is called internally during component creation. The ID of a deleted component is not issued again to another component, because we want IDs to be unique during the whole simulation.

◆ deregisterComponent()

void deregisterComponent ( cComponent component)

Deregisters the component from cSimulation. It is called internally from cComponent's destructor.

◆ getLastComponentId()

int getLastComponentId ( ) const
inline

Returns the highest used component ID.

◆ getModuleByPath()

cModule* getModuleByPath ( const char *  modulePath) const

Finds a module by its path. The path is a string of module names separated by dots. Inclusion of the toplevel module's name in the path is optional. The toplevel module's name may also be written as "<root>". Note that this method, unlike its counterpart in cModule, does not accept relative paths (those that start with '.' or '^'.)

This method never returns nullptr. If the module was not found, an exception is thrown.

See also
findModuleByPath(), cModule::getModuleByPath()

◆ findModuleByPath()

cModule* findModuleByPath ( const char *  modulePath) const

Finds a module by its path. The path is a string of module names separated by dots. Inclusion of the toplevel module's name in the path is optional. The toplevel module's name may also be written as "<root>". Note that this method, unlike its counterpart in cModule, does not accept relative paths (those that start with '.' or '^'.)

If the module was not found or the empty string was given as input, this method returns nullptr.

See also
getModuleByPath(), cModule::findModuleByPath()

◆ getComponent()

cComponent* getComponent ( int  id) const
inline

Looks up a component (module or channel) by ID. If the ID does not identify a component (e.g. invalid ID or component already deleted), it returns nullptr.

◆ getModule()

cModule* getModule ( int  id) const
inline

Looks up a module by ID. If the ID does not identify a module (e.g. invalid ID, module already deleted, or object is not a module), it returns nullptr.

References cComponent::isModule().

Referenced by cMessage::getArrivalModule(), cTopology::Node::getModule(), and cMessage::getSenderModule().

◆ getChannel()

cChannel* getChannel ( int  id) const
inline

Looks up a channel by ID. If the ID does not identify a channel (e.g. invalid ID, channel already deleted, or object is not a channel), it returns nullptr.

References cComponent::isChannel().

◆ setSystemModule()

void setSystemModule ( cModule module)

Designates the system module, the top-level module in the model.

◆ getSystemModule()

cModule* getSystemModule ( ) const
inline

Returns pointer to the system module, the top-level module in the model.

◆ loadNedSourceFolder()

static int loadNedSourceFolder ( const char *  folderName,
const char *  excludedPackages = "" 
)
static

Load all NED files from a NED source folder. This involves visiting each subdirectory, and loading all "*.ned" files from there. The given folder is assumed to be the root of the NED package hierarchy. A list of packages to skip may be specified in the excludedPackages parameter (items must be separated with a semicolon).

The function returns the number of NED files loaded.

Note: doneLoadingNedFiles() must be called after the last loadNedSourceFolder()/loadNedFile()/loadNedText() call.

◆ loadNedFile()

static void loadNedFile ( const char *  nedFilename,
const char *  expectedPackage = nullptr,
bool  isXML = false 
)
static

Load a single NED file. If the expected package is given (non-nullptr), it should match the package declaration inside the NED file.

Note: doneLoadingNedFiles() must be called after the last loadNedSourceFolder()/loadNedFile()/loadNedText() call.

◆ loadNedText()

static void loadNedText ( const char *  name,
const char *  nedText,
const char *  expectedPackage = nullptr,
bool  isXML = false 
)
static

Parses and loads the NED source code passed in the nedtext argument. The name argument will be used as filename in error messages, and and should be unique among the files loaded. If the expected package is given (non-nullptr), it should match the package declaration inside the NED file.

Note: doneLoadingNedFiles() must be called after the last loadNedSourceFolder()/loadNedFile()/loadNedText() call.

◆ doneLoadingNedFiles()

static void doneLoadingNedFiles ( )
static

To be called after all NED folders / files have been loaded (see loadNedSourceFolder()/loadNedFile()/loadNedText()). Issues errors for components that could not be fully resolved because of missing base types or interfaces.

◆ getNedPackageForFolder()

static std::string getNedPackageForFolder ( const char *  folder)
static

Returns the NED package that corresponds to the given folder. Returns "" for the default package, and "-" if the folder is outside all NED folders.

◆ setScheduler()

void setScheduler ( cScheduler scheduler)

Installs a scheduler object. This method may only be called before or between simulations, when there is no network set up. The cSimulation object will be responsible for deallocating the scheduler object.

◆ getScheduler()

cScheduler* getScheduler ( ) const
inline

Returns the scheduler object.

◆ setFES()

void setFES ( cFutureEventSet fes)

Sets the future event set. This method may only be called before or between simulations, when there is no network set up. The cSimulation object will be responsible for deallocating the FES object.

◆ getFES()

cFutureEventSet* getFES ( ) const
inline

Returns the future event set data structure used by the simulation.

◆ setSimulationTimeLimit()

void setSimulationTimeLimit ( simtime_t  simTimeLimit)

Sets the simulation stop time be scheduling an appropriate "end-simulation" event. May only be called once per run.

◆ setupNetwork()

void setupNetwork ( cModuleType networkType)

Builds a new network.

◆ callInitialize()

void callInitialize ( )

Should be called after setupNetwork(), but before the first executeEvent() call. Includes initialization of the modules, that is, invokes callInitialize() on the system module.

◆ callFinish()

void callFinish ( )

Recursively calls finish() on the modules of the network. This method simply invokes callfinish() on the system module.

◆ deleteNetwork()

void deleteNetwork ( )

Cleans up the network currently set up. This involves deleting all modules and deleting the messages in the scheduled-event list.

◆ getSimulationStage()

int getSimulationStage ( ) const
inline

Returns the current simulation stage: network building (CTX_BUILD), network initialization (CTX_INIT), simulation execution (CTX_EVENT), simulation finalization (CTX_FINISH), network cleanup (CTX_CLEANUP), or other (CTX_NONE).

◆ getNetworkType()

cModuleType* getNetworkType ( ) const
inline

Returns the cModuleType object that was instantiated to set up the current simulation model.

◆ setSimTime()

void setSimTime ( simtime_t  time)
inline

INTERNAL USE ONLY. This method should NEVER be invoked from simulation models, only from scheduler classes subclassed from cScheduler.

◆ getSimTime()

simtime_t_cref getSimTime ( ) const
inline

Returns the current simulation time. (It is also available via the global simTime() function.) Between events it returns the time of the last executed event.

Referenced by cMessage::setTimestamp(), and omnetpp::simTime().

◆ getEventNumber()

eventnumber_t getEventNumber ( ) const
inline

Returns the sequence number of current event. Between events it returns the sequence number of the next event.

◆ getWarmupPeriod()

simtime_t_cref getWarmupPeriod ( ) const
inline

Returns the length of the initial warm-up period from the configuration. Modules that compute and record scalar results manually (via recordScalar(), recordStatistic(), etc.) should be implemented in a way that they ignore observations generated during the warm-up period. cOutVector objects, and results recorded via the signals mechanism automatically obey the warm-up period and need not be modified. The warm-up period is useful for steady-state simulations.

◆ setWarmupPeriod()

void setWarmupPeriod ( simtime_t  t)
inline

INTERNAL USE ONLY. Sets the warm-up period.

◆ guessNextEvent()

cEvent* guessNextEvent ( )

Returns the likely next event in the simulation. Intended to be called from a user interface library for displaying simulation status information. Delegates to cScheduler::guessNextEvent().

◆ guessNextModule()

cSimpleModule* guessNextModule ( )

Returns the module associated with the likely next event, or nullptr if there is no such module. Based on guessNextEvent(); see further comments there.

◆ guessNextSimtime()

simtime_t guessNextSimtime ( )

Returns the simulation time of the likely next event, or -1 if there is none. Based on guessNextEvent(); see further comments there.

◆ takeNextEvent()

cEvent* takeNextEvent ( )

The scheduler function. Returns the next event from the FES. If there is no more event (FES is empty), it throws cTerminationException.

A nullptr return value means that there is no error but execution was stopped by the user (e.g. with STOP button on the GUI) while the scheduler object was waiting for external synchronization.

Delegates to cScheduler::takeNextEvent().

◆ putBackEvent()

void putBackEvent ( cEvent event)

Undo for takeNextEvent(); see cScheduler's similar method for details.

◆ executeEvent()

void executeEvent ( cEvent event)

Executes an event as part of the simulation. Also increments the event number (see getEventNumber()).

◆ callRefreshDisplay()

void callRefreshDisplay ( )

Invoke callRefreshDisplay() on the system module.

◆ transferTo()

void transferTo ( cSimpleModule module)

Switches to the given simple module's coroutine. This method is invoked from executeEvent() for activity()-based modules.

◆ transferToMain()

void transferToMain ( )

Switches to main coroutine.

◆ insertEvent()

void insertEvent ( cEvent event)

Inserts the given event into the future events queue while assigning the current event to its scheduling event. Used internally by cSimpleModule::scheduleAt() and various other cSimpleModule methods.

◆ setContext()

void setContext ( cComponent component)

Sets the component (module or channel) in context. Used internally.

◆ setContextType()

void setContextType ( ContextType  type)
inline

Sets the context type for the context module. Used internally.

◆ setGlobalContext()

void setGlobalContext ( )
inline

Sets global context. Used internally.

◆ getActivityModule()

cSimpleModule* getActivityModule ( ) const
inline

Returns the module whose activity() method is currently active. Returns nullptr if no module is running, or the current module uses handleMessage().

◆ getContext()

cComponent* getContext ( ) const
inline

Returns the component (module or channel) currently in context.

◆ getContextType()

ContextType getContextType ( ) const
inline

Returns one of the CTX_BUILD, CTX_INITIALIZE, CTX_EVENT, CTX_FINISH constants, depending on what the module in context is doing. In case of nested contexts (e.g. when a module is dynamically created, initialized or manually finalized during simulation), the innermost context type is returned. The return value is only valid if getContextModule() != nullptr.

◆ getContextModule()

cModule* getContextModule ( ) const

If the current context is a module, returns its pointer, otherwise returns nullptr.

◆ getContextSimpleModule()

cSimpleModule* getContextSimpleModule ( ) const

Returns the module currently in context as a simple module. If the module in context is not a simple module, returns nullptr. This is a convenience function which simply calls getContextModule().

◆ requestTrapOnNextEvent()

void requestTrapOnNextEvent ( )
inline

Request the next handleMessage() or activity() to execute a debugger interrupt. (If the program is not run under a debugger, that will usually result in a crash.)

◆ clearTrapOnNextEvent()

void clearTrapOnNextEvent ( )
inline

Clear the previous requestTrapOnNextEvent() call.

◆ isTrapOnNextEventRequested()

bool isTrapOnNextEventRequested ( ) const
inline

Returns true if there is a pending request to execute a debugger interrupt on the next event.

◆ getUniqueNumber()

unsigned long getUniqueNumber ( )

This function is guaranteed to return a different integer every time it is called (usually 0, 1, 2, ...). This method works with parallel simulation as well, so it is recommended over incrementing a global variable. Useful for generating unique network addresses, etc.

◆ snapshot()

void snapshot ( cObject obj,
const char *  label 
)

Writes a snapshot of the given object and its children to the textual snapshot file. This method is called internally from cSimpleModule's snapshot().

◆ getFingerprintCalculator()

cFingerprintCalculator* getFingerprintCalculator ( )
inline

Returns the object used for fingerprint calculation. It returns nullptr if no fingerprint is being calculated during this simulation run.

◆ setFingerprintCalculator()

void setFingerprintCalculator ( cFingerprintCalculator fingerprint)

Installs a new fingerprint object, used for fingerprint calculation.


The documentation for this class was generated from the following file: