#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:

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

cModule *	getModuleByPath (const char *modulePath) const

cModule *	findModuleByPath (const char *modulePath) const

cComponent *	getComponent (int id) const

cModule *	getModule (int id) const

cChannel *	getChannel (int id) const

void	setSystemModule (cModule *module)

cModule *	getSystemModule () const

Setting up and finishing a simulation run.
void	setScheduler (cScheduler *scheduler)

cScheduler *	getScheduler () const

void	setFES (cFutureEventSet *fes)

cFutureEventSet *	getFES () 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

cModuleType *	getNetworkType () 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.
cEvent *	guessNextEvent ()

cSimpleModule *	guessNextModule ()

simtime_t	guessNextSimtime ()

cEvent *	takeNextEvent ()

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 ()

cSimpleModule *	getActivityModule () const

cComponent *	getContext () const

ContextType	getContextType () const

cModule *	getContextModule () const

cSimpleModule *	getContextSimpleModule () const

void	requestTrapOnNextEvent ()

void	clearTrapOnNextEvent ()

bool	isTrapOnNextEventRequested () const

Miscellaneous.
unsigned long	getUniqueNumber ()

void	snapshot (cObject obj, const char label)

cFingerprintCalculator *	getFingerprintCalculator ()

void	setFingerprintCalculator (cFingerprintCalculator *fingerprint)

Public Member Functions inherited from cNamedObject
	cNamedObject ()

	cNamedObject (const char *name, bool namepooling=true)

	cNamedObject (const cNamedObject &obj)

virtual	~cNamedObject ()

cNamedObject &	operator= (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 cObject *	getThisPtr () const

virtual std::string	str () const

virtual std::ostream &	printOn (std::ostream &os) const

virtual cObject *	dup () const

virtual cObject *	getOwner () const

virtual bool	isOwnedObject () const

virtual bool	isSoftOwner () const

cObject *	findObject (const char *name, bool deep=true)

virtual cClassDescriptor *	getDescriptor () 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
cEnvir *	getEnvir () const

static cSimulation *	getActiveSimulation ()

static cEnvir *	getActiveEnvir ()

static void	setActiveSimulation (cSimulation *sim)

static void	setStaticEnvir (cEnvir *env)

static cEnvir *	getStaticEnvir ()

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:

csimulation.h

Description

Public Member Functions

Static Public Member Functions

Accessing and switching the active simulation object

Additional Inherited Members

Constructor & Destructor Documentation

◆ cSimulation()

◆ ~cSimulation()

Member Function Documentation

◆ forEachChild()

◆ getFullPath()

◆ getActiveSimulation()

◆ getActiveEnvir()

◆ setActiveSimulation()

◆ setStaticEnvir()

◆ getStaticEnvir()

◆ getEnvir()

◆ registerComponent()

◆ deregisterComponent()

◆ getLastComponentId()

◆ getModuleByPath()

◆ findModuleByPath()

◆ getComponent()

◆ getModule()

◆ getChannel()

◆ setSystemModule()

◆ getSystemModule()

◆ loadNedSourceFolder()

◆ loadNedFile()

◆ loadNedText()

◆ doneLoadingNedFiles()

◆ getNedPackageForFolder()

◆ setScheduler()

◆ getScheduler()

◆ setFES()

◆ getFES()

◆ setSimulationTimeLimit()

◆ setupNetwork()

◆ callInitialize()

◆ callFinish()

◆ deleteNetwork()

◆ getSimulationStage()

◆ getNetworkType()

◆ setSimTime()

◆ getSimTime()

◆ getEventNumber()

◆ getWarmupPeriod()

◆ setWarmupPeriod()

◆ guessNextEvent()

◆ guessNextModule()

◆ guessNextSimtime()

◆ takeNextEvent()

◆ putBackEvent()

◆ executeEvent()

◆ callRefreshDisplay()

◆ transferTo()

◆ transferToMain()

◆ insertEvent()

◆ setContext()

◆ setContextType()

◆ setGlobalContext()

◆ getActivityModule()

◆ getContext()

◆ getContextType()

◆ getContextModule()

◆ getContextSimpleModule()

◆ requestTrapOnNextEvent()

◆ clearTrapOnNextEvent()

◆ isTrapOnNextEventRequested()

◆ getUniqueNumber()

◆ snapshot()

◆ getFingerprintCalculator()

◆ setFingerprintCalculator()