cSimulation Class Reference
[Simulation core classes, Internal classes]

Simulation manager class. More...

#include <csimulation.h>

Inheritance diagram for cSimulation:

List of all members.

Public Member Functions
Constructor, destructor.
	cSimulation (const char *name, cEnvir *env)
virtual	~cSimulation ()
Redefined cObject member functions.
virtual void	forEachChild (cVisitor *v)
virtual std::string	getFullPath () const
Accessing modules.
int	registerModule (cModule *mod)
void	deregisterModule (cModule *mod)
int	getLastModuleId () const
cModule *	getModuleByPath (const char *modulepath) const
cModule *	getModule (int id) const
_OPPDEPRECATED cModule &	operator[] (int id) const
void	setSystemModule (cModule *p)
cModule *	getSystemModule () const
Setting up and finishing a simulation run.
void	setScheduler (cScheduler *scheduler)
cScheduler *	getScheduler () const
void	setupNetwork (cModuleType *networkType)
void	startRun ()
void	callFinish ()
void	endRun ()
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 context switching during simulation.
cSimpleModule *	selectNextModule ()
cMessage *	guessNextEvent ()
cSimpleModule *	guessNextModule ()
simtime_t	guessNextSimtime ()
void	doOneEvent (cSimpleModule *m)
void	transferTo (cSimpleModule *p)
void	transferToMain ()
void	insertMsg (cMessage *msg)
void	setContext (cComponent *p)
void	setContextType (int ctxtype)
void	setGlobalContext ()
cSimpleModule *	getActivityModule () const
cComponent *	getContext () const
int	getContextType () const
cModule *	getContextModule () const
cSimpleModule *	getContextSimpleModule () const
void	requestTrapOnNextEvent ()
void	clearTrapOnNextEvent ()
bool	isTrapOnNextEventRequested () const
Miscellaneous.
unsigned long	getUniqueNumber ()
bool	snapshot (cObject *obj, const char *label)
cHasher *	getHasher ()
void	setHasher (cHasher *hasher)
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)
static void	loadNedFile (const char *nedfname, const char *expectedPackage=NULL, bool isXML=false)
static void	loadNedText (const char *name, const char *nedtext, const char *expectedPackage=NULL, bool isXML=false)
static void	doneLoadingNedFiles ()
static std::string	getNedPackageForFolder (const char *folder)
Friends
class	cSimpleModule
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 ()

---

Detailed 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, Tkenv) to set up and run simulations).

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

---

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.

---

Member Function Documentation

void cSimulation::callFinish

(

)

Recursively calls finish() on the modules of the network.

This method simply invokes callfinish() on the system module.

void cSimulation::deleteNetwork

(

)

Cleans up the network currently set up.

This involves deleting all modules and deleting the messages in the scheduled-event list.

void cSimulation::deregisterModule

(

cModule *

mod

)

Deregisters the module from cSimulation.

It is called internally from cModule destructor.

static void cSimulation::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.

void cSimulation::doOneEvent

(

cSimpleModule *

m

)

Executes one event.

The argument should be the module returned by selectNextModule(); that is, the module to which the next event (lowest timestamp event in the FES) belongs. Also increments the event number (returned by getEventNumber()).

virtual void cSimulation::forEachChild

(

cVisitor *

v

)

[virtual]

Calls v->visit(this) for each contained object.

See cObject for more details.

Reimplemented from cObject.

static cEnvir* cSimulation::getActiveEnvir

(

)

[inline, static]

Returns the environment object for the active simulation.

Never returns NULL; setActiveSimulation(NULL) will cause a static "do-nothing" instance to step in.

static cSimulation* cSimulation::getActiveSimulation

(

)

[inline, static]

Returns the active simulation object.

May be NULL.

cSimpleModule* cSimulation::getActivityModule

(

)

const [inline]

Returns the module whose activity() method is currently active.

Returns NULL if no module is running, or the current module uses handleMessage().

cSimpleModule* cSimulation::getContextSimpleModule

(

)

const

Returns the module currently in context as a simple module.

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

int cSimulation::getContextType

(

)

const [inline]

Returns value only valid if getContextModule()!=NULL.

Returns one of: CTX_BUILD, CTX_INITIALIZE, CTX_EVENT, CTX_FINISH, 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.

virtual std::string cSimulation::getFullPath

(

)

const [virtual]

Redefined.

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

Reimplemented from cObject.

cHasher* cSimulation::getHasher

(

)

[inline]

Returns the object used for fingerprint calculation.

It returns NULL if no fingerprint is being calculated during this simulation run.

cModule* cSimulation::getModule

(

int

id

)

const [inline]

Looks up a module by ID.

If the module does not exist, returns NULL.

References cModule::size().

cModule* cSimulation::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. Returns NULL if the module is not found.

static std::string cSimulation::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.

simtime_t_cref cSimulation::getSimTime

(

)

const [inline]

Returns the current simulation time.

(It is also available via the global simTime() function.)

unsigned long cSimulation::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.

simtime_t_cref cSimulation::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.

cMessage* cSimulation::guessNextEvent

(

)

To be called between events from the environment of the simulation (e.g.

from Tkenv), this function returns a pointer to the event at the head of the FES. It is only guaranteed to be the next event with sequential simulation; with parallel, distributed or real-time simulation there might be another event coming from other processes with a yet smaller timestamp.

This method is careful not to change anything. It never throws an exception, and especially, it does NOT invoke the scheduler (see cScheduler) because e.g. its parallel simulation incarnations might do subtle things to keep events synchronized in various partitions of the parallel simulation.

cSimpleModule* cSimulation::guessNextModule

(

)

To be called between events from the environment of the simulation (e.g.

from Tkenv), this function returns the module associated with the event at the head of the FES. It returns NULL if the FES is empty, there is no module associated with the event, or the module has already finished.

Based on guessNextEvent(); see further comments there.

simtime_t cSimulation::guessNextSimtime

(

)

To be called between events from the environment of the simulation (e.g.

Tkenv), this function returns the simulation time of the event at the head of the FES. In contrast, simTime() returns the time of the last executed (or currently executing) event. Returns a negative value if the FES is empty.

Based on guessNextEvent(); see further comments there.

void cSimulation::insertMsg

(

cMessage *

msg

)

Inserts the given message into the future events queue while assigning the current event to its scheduling event.

Used internally by cSimpleModule::scheduleAt() and various other cSimpleModule methods.

static void cSimulation::loadNedFile	(	const char *	nedfname,
		const char *	expectedPackage = NULL,
		bool	isXML = false
	)			[static]

Load a single NED file.

If the expected package is given (non-NULL), it should match the package declaration inside the NED file.

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

static int cSimulation::loadNedSourceFolder

(

const char *

foldername

)

[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. Returns the number of files loaded.

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

static void cSimulation::loadNedText	(	const char *	name,
		const char *	nedtext,
		const char *	expectedPackage = NULL,
		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-NULL), it should match the package declaration inside the NED file.

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

_OPPDEPRECATED cModule& cSimulation::operator[]

(

int

id

)

const [inline]

DEPRECATED because it might return null reference; use getModule(int) instead.

Same as getModule(int), only this returns reference instead of pointer.

References cModule::size().

int cSimulation::registerModule

(

cModule *

mod

)

Registers the module in cSimulation and assigns a module Id.

It is called internally during module creation. The Id of a deleted module is not issued again to another module, because we want module Ids to be unique during the whole simulation.

void cSimulation::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.)

cSimpleModule* cSimulation::selectNextModule

(

)

The scheduler function.

Returns the module to which the next event (lowest timestamp event in the FES) belongs.

If there is no more event (FES is empty), it throws cTerminationException.

A NULL return value means that there is no error but execution was stopped by the user (e.g. with STOP button on the GUI) while selectNextModule() --or rather, the installed cScheduler object-- was waiting for external synchronization.

static void cSimulation::setActiveSimulation

(

cSimulation *

sim

)

[static]

Activate the given simulation object, and its associated environment object.

NULL is also accepted; it will cause the static environment object to step in (see getStaticEnvir()).

void cSimulation::setContext

(

cComponent *

p

)

Sets the component (module or channel) in context.

Used internally.

void cSimulation::setContextType

(

int

ctxtype

)

[inline]

Sets the context type (see CTX_xxx constants).

Used internally.

void cSimulation::setGlobalContext

(

)

[inline]

Sets global context.

Used internally.

void cSimulation::setScheduler

(

cScheduler *

scheduler

)

Installs a scheduler object.

This may only be called when no network is set up. The cSimulation object will be responsible for deallocating the scheduler object.

void cSimulation::setSimTime

(

simtime_t

time

)

[inline]

INTERNAL USE ONLY.

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

static void cSimulation::setStaticEnvir

(

cEnvir *

env

)

[static]

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

The argument cannot be NULL.

void cSimulation::setWarmupPeriod

(

simtime_t

t

)

[inline]

INTERNAL USE ONLY.

Sets the warm-up period.

bool cSimulation::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().

void cSimulation::startRun

(

)

Should be called after setupNetwork(), but before the first doOneEvent() call.

Includes initialization of the modules, that is, invokes callInitialize() on the system module.

void cSimulation::transferTo

(

cSimpleModule *

p

)

Switches to simple module's coroutine.

This method is invoked from doOneEvent() for activity()-based modules.

---

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

• csimulation.h