cEnvir Class Reference
[User interface: cEnvir and ev, Extension interfaces]

cEnvir represents the "environment" of the simulation. More...

#include <cenvir.h>

Inheritance diagram for cEnvir:

Public Member Functions
Constructor, destructor.

	cEnvir ()
virtual	~cEnvir ()
Methods to be called by the simulation kernel to notify the environment about events.

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
virtual void	undisposedObject (cObject *obj)
Methods called by the simulation kernel to access configuration settings.

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 ()
Input/output methods called from simple modules or the simulation kernel.

virtual bool	isGUI () const =0
bool	isDisabled () const
cEnvir &	operator<< (const std::string &t)
template<typename T >
cEnvir &	operator<< (const T &t)
cEnvir &	operator<< (std::ostream &(t)(std::ostream &))
std::ostream &	getOStream ()
virtual void	bubble (cComponent component, const char text)=0
virtual void	printfmsg (const char *fmt,...)
virtual int	printf (const char *fmt,...)
virtual cEnvir &	flush ()=0
virtual std::string	gets (const char prompt, const char defaultreply=NULL)=0
virtual bool	askYesNo (const char *fmt,...)
Access to RNGs.

virtual int	getNumRNGs () const =0
virtual cRNG *	getRNG (int k)=0
virtual void	getRNGMappingFor (cComponent *component)=0
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).
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
Scalar statistics.
The method cComponent::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).
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
Statistic recording.

virtual void	addResultRecorders (cComponent component, simsignal_t signal, const char statisticName, cProperty *statisticTemplateProperty)=0
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).
virtual std::ostream *	getStreamForSnapshot ()=0
virtual void	releaseStreamForSnapshot (std::ostream *os)=0
Miscellaneous functions.

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

Detailed Description

cEnvir represents the "environment" of the simulation.

cEnvir is a common facade for the Cmdenv and Tkenv user interfaces (and any other future user interface). The cEnvir object can be accessed via cSimulation::getActiveEnvir() or the ev macro.

The default 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.

Member Function Documentation

virtual void cEnvir::addResultRecorders	(	cComponent *	component,
		simsignal_t	signal,
		const char *	statisticName,
		cProperty *	statisticTemplateProperty
	)			`[pure virtual]`

Adds result recording listeners for the given signal on the given component.

The result will be recorded to the the given component, with a name equal to or derived from the given statisticName. The statisticTemplateProperty parameter is expected to point to a NED property with content similar to properties. The computation and result type (scalar, vector, etc) will be taken from the 'record' key of statisticTemplateProperty in the same way as with . Also similar to , key-value pairs of statisticTemplateProperty will be recorded as result attributes.

In statisticTemplateProperty, the 'source' key will be ignored (because the signal given as parameter will be used as source). The actual name and index of statisticTemplateProperty will also be ignored. (With , the index holds the result name, but here the name is explicitly specified in the statisticName parameter.)

The purpose of this function is to allow setting up signal-based result recording dynamically when static configuration via properties is not possible, e.g. because the set of signals to record is only known at runtime.

Implemented in cNullEnvir.

virtual bool cEnvir::askYesNo	(	const char *	fmt,
			...
	)			`[virtual]`

Asks the user a yes/no question.

The question text is expected in printf() format (format string + arguments). The return value is true for "yes", and false for "no".

virtual void cEnvir::attachDebugger ( ) [pure virtual]

Starts an external debugger program and attaches it to this process.

The command line to start the debugger can be configured.

Implemented in cNullEnvir.

virtual void cEnvir::beginSend ( cMessage * msg ) [pure virtual]

Notifies the environment that a message is being sent from a simple module.

beginSend() will be followed by a messageSendDirect() (optional, only present when cSimpleModule::sendDirect() was called), several messageSendHop() calls (one for each connection in the path), and finally an endSend().

Implemented in cNullEnvir.

virtual void cEnvir::componentMethodBegin	(	cComponent *	from,
		cComponent *	to,
		const char *	methodFmt,
		va_list	va,
		bool	silent
	)			`[pure virtual]`

Notifies the environment that one component (module) called a member function of another component.

This hook enables a graphical user interface to animate the method call in the network diagram. Pass methodFmt==NULL for Enter_Method_Silent.

Implemented in cNullEnvir.

virtual void cEnvir::configure ( cComponent * component ) [pure virtual]

Called when a module or channel has been created and installed in the model, and lets the environment perform extra setup.

One use is to add signal listeners for result recording.

Implemented in cNullEnvir.

virtual void cEnvir::endSend ( cMessage * msg ) [pure virtual]

Closes a beginSend() sequence.

See also:: beginSend()

Implemented in cNullEnvir.

virtual cEnvir& cEnvir::flush ( ) [pure virtual]

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.

Implemented in cNullEnvir.

virtual void cEnvir::flushXMLDocumentCache ( ) [pure virtual]

Clears the cache of loaded XML documents, and deletes the corresponding cXMLElement trees.

CAUTION: As of version 4.1, this is not a safe operation, as module parameters (cPar) of type "xml" hold pointers to the element trees returned by getXMLDocument(), and this method makes those pointers invalid.

Implemented in cNullEnvir.

virtual void cEnvir::flushXMLParsedContentCache ( ) [pure virtual]

Clears the cache of parsed XML content strings, and deletes the corresponding cXMLElement trees.

CAUTION: As of version 4.1, this is not a safe operation, as module parameters (cPar) of type "xml" hold pointers to the element trees returned by getXMLDocument(), and this method makes those pointers invalid.

Implemented in cNullEnvir.

virtual void cEnvir::forgetParsedXMLString ( const char * content ) [pure virtual]

Removes the given document from the XML document cache (if cached), and deletes the object tree from memory.

After forgetXMLDocument(), cXMLElement objects returned for the same content string by getParsedXMLString() should no longer be referenced. The call has no effect if the given string has not yet been parsed.

CAUTION: As of version 4.1, this is not a safe operation! Module parameters (cPar) of type "xml" hold pointers to the element trees returned by getXMLDocument(), and this method makes those pointers invalid.

Implemented in cNullEnvir.

virtual void cEnvir::forgetXMLDocument ( const char * filename ) [pure virtual]

Removes the given document from the XML document cache (if cached), and deletes the object tree from memory.

Further getXMLDocument() calls will reload the file from the disk. After forgetXMLDocument(), cXMLElement objects returned for the same document by getXMLDocument() should no longer be referenced. The call has no effect if the given file does not exist or has not yet been loaded.

CAUTION: As of version 4.1, this is not a safe operation! Module parameters (cPar) of type "xml" hold pointers to the element trees returned by getXMLDocument(), and this method makes those pointers invalid.

Implemented in cNullEnvir.

virtual cConfiguration* cEnvir::getConfig ( ) [pure virtual]

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

This method 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.

Implemented in cNullEnvir.

virtual cConfigurationEx* cEnvir::getConfigEx ( ) [virtual]

Returns the configuration as used by the Envir library.

It will throw an error if the configuration object does not subclass from cConfigurationEx. This method should not be used from the simulation kernel or model code.

std::ostream& cEnvir::getOStream ( ) [inline]

Returns the std::ostream instance where '<<' operators delegate.

Writes will be eventually delegated to cEnvir::sputn(), after buffering.

virtual cXMLElement* cEnvir::getParsedXMLString	(	const char *	content,
		const char *	xpath = `NULL`
	)			`[pure virtual]`

Returns the parsed form of an XML content string.

The first argument is the XML content string. 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 is 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 there was a parse error or if the given path expression is invalid. It returns NULL if the element denoted by the path expression does not exist in the document.

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

Implemented in cNullEnvir.

virtual std::ostream* cEnvir::getStreamForSnapshot ( ) [pure virtual]

Returns a stream where a snapshot can be written.

Called from cSimulation::snapshot().

Implemented in cNullEnvir.

virtual cXMLElement* cEnvir::getXMLDocument	(	const char *	filename,
		const char *	xpath = `NULL`
	)			`[pure virtual]`

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 is 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, there was a parse error, or the given path expression is invalid. It returns NULL if the element denoted by the path expression does not 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.

Implemented in cNullEnvir.

virtual bool cEnvir::idle ( ) [pure virtual]

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

Implemented in cNullEnvir.

bool cEnvir::isDisabled ( ) const [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.isDisabled())  ev << "Packet " << msg->getName() << " received";

which can be abbreviated with the EV macro:

     EV << "Packet " << msg->getName() << " received";

virtual bool cEnvir::isGUI ( ) const [pure virtual]

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.

Implemented in cNullEnvir.

virtual bool cEnvir::isModuleLocal	(	cModule *	parentmod,
		const char *	modname,
		int	index
	)			`[pure virtual]`

Used for parallel distributed simulation.

Returns true if the named future submodule of parentmod is (or will have any submodule) in the local partition, and false otherwise. index should be -1 if the submodule is not in a module vector.

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

Implemented in cNullEnvir.

virtual void cEnvir::messageCancelled ( cMessage * msg ) [pure virtual]

Notifies the environment that a scheduled message was cancelled.

See also:: cSimpleModule::cancelEvent()

Implemented in cNullEnvir.

virtual void cEnvir::messageCloned	(	cMessage *	msg,
		cMessage *	clone
	)			`[pure virtual]`

Notifies the environment that a message object is being cloned.

This is called from the cMessage copy constructor.

Implemented in cNullEnvir.

virtual void cEnvir::messageCreated ( cMessage * msg ) [pure virtual]

Notifies the environment that a message object is being created.

This is called from the cMessage constructor.

Implemented in cNullEnvir.

virtual void cEnvir::messageDeleted ( cMessage * msg ) [pure virtual]

Notifies the environment that a message object is being deleted.

This is called from the cMessage destructor, so any information added to cMessage via subclassing is already lost at the time of the call.

Implemented in cNullEnvir.

virtual void cEnvir::messageScheduled ( cMessage * msg ) [pure virtual]

Notifies the environment that a message was scheduled.

See also:: cSimpleModule::scheduleAt()

Implemented in cNullEnvir.

virtual void cEnvir::messageSendDirect	(	cMessage *	msg,
		cGate *	toGate,
		simtime_t	propagationDelay,
		simtime_t	transmissionDelay
	)			`[pure virtual]`

Part of the beginSend() sequence.

See also:: beginSend()

Implemented in cNullEnvir.

virtual void cEnvir::messageSendHop	(	cMessage *	msg,
		cGate *	srcGate,
		simtime_t	propagationDelay,
		simtime_t	transmissionDelay
	)			`[pure virtual]`

Part of the beginSend() sequence.

See also:: beginSend()

Implemented in cNullEnvir.

virtual void cEnvir::messageSendHop	(	cMessage *	msg,
		cGate *	srcGate
	)			`[pure virtual]`

Part of the beginSend() sequence.

See also:: beginSend()

Implemented in cNullEnvir.

virtual void cEnvir::messageSent_OBSOLETE	(	cMessage *	msg,
		cGate *	directToGate = `NULL`
	)			`[pure virtual]`

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

Implemented in cNullEnvir.

virtual void cEnvir::moduleCreated ( cModule * newmodule ) [pure virtual]

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.

Implemented in cNullEnvir.

virtual void cEnvir::moduleDeleted ( cModule * module ) [pure virtual]

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

This method is called from cModule destructor, so the "real" type (getClassName() and everything from the actual subclass) is already lost at this point, however getName(), getFullName(), getFullPath(), 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.

Implemented in cNullEnvir.

virtual void cEnvir::objectDeleted ( cObject * object ) [inline, virtual]

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.

Reimplemented in cNullEnvir.

template<typename T >

cEnvir& cEnvir::operator<< ( const T & t ) [inline]

Overloaded << operator to make cEnvir behave like an ostream.

This method can be used by modules and channels to display debugging output. It is up to the user interface implementation to display the text in the way it wants. The text is usually associated with the module or channel in context (see cSimulation::getContext()), and may get displayed in the module's debug window, or enabled/disabled per module.

See also:: getOStream()

cEnvir& cEnvir::operator<< ( const std::string & t ) [inline]

Overloaded << operator to make cEnvir behave like an ostream.

See also:: getOStream()

virtual int cEnvir::printf	(	const char *	fmt,
			...
	)			`[virtual]`

This method can be used by modules and channels to display debugging output.

It is up to the user interface implementation to display the text in the way it wants. The text is usually associated with the module or channel in context (see cSimulation::getContext()), and may get displayed in the module's debug window, or enabled/disabled per module.

The function's arguments are identical to the standard <stdio.h> printf(). It is recommended to use C++-style I/O (operator<<) instead of this function.

virtual void cEnvir::printfmsg	(	const char *	fmt,
			...
	)			`[virtual]`

Displays the given text in a dialog box.

This function should not be used by simple modules. Delegates to putsmsg().

virtual bool cEnvir::recordInOutputVector	(	void *	vechandle,
		simtime_t	t,
		double	value
	)			`[pure virtual]`

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

Implemented in cNullEnvir.

virtual void cEnvir::recordStatistic	(	cComponent *	component,
		const char *	name,
		cStatistic *	statistic,
		opp_string_map *	attributes = `NULL`
	)			`[pure virtual]`

Records a statistic object (histogram, etc) into the scalar result file.

This operation may invoke the transform() method on the histogram object.

Implemented in cNullEnvir.

virtual void* cEnvir::registerOutputVector	(	const char *	modulename,
		const char *	vectorname
	)			`[pure virtual]`

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

The returned value is a handle that identifies the vector in subsequent recordInOutputVector() and deregisterOutputVector() calls. The handle may have any value (it does not have to be a valid pointer), but it should NOT be NULL.

Implemented in cNullEnvir.

virtual void cEnvir::simulationEvent ( cMessage * msg ) [pure virtual]

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.

Implemented in cNullEnvir.

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

cenvir.h

cEnvir Class Reference [User interface: cEnvir and ev, Extension interfaces]

Public Member Functions

Detailed Description

Member Function Documentation

cEnvir Class Reference
[User interface: cEnvir and ev, Extension interfaces]