cSimpleModule Class Reference
[Simulation core classes]

Base class for all simple module classes. More...

#include <csimplemodule.h>

Inheritance diagram for cSimpleModule:

Public Member Functions
Constructors, destructor, assignment.

	cSimpleModule (unsigned stacksize=0)
	cSimpleModule (const char dummy1, cModule dummy2, unsigned stacksize)
virtual	~cSimpleModule ()
Redefined cObject member functions.

virtual std::string	info () const
virtual void	forEachChild (cVisitor *v)
Redefined cModule functions.

virtual void	scheduleStart (simtime_t t)
virtual void	deleteModule ()
Information about the module.

bool	usesActivity () const
bool	isTerminated () const
Debugging aids.

bool	snapshot (cObject obj=NULL, const char label=NULL)
Message sending.

int	send (cMessage *msg, int gateid)
int	send (cMessage msg, const char gatename, int gateindex=-1)
int	send (cMessage msg, cGate outputgate)
int	sendDelayed (cMessage *msg, simtime_t delay, int gateid)
int	sendDelayed (cMessage msg, simtime_t delay, const char gatename, int gateindex=-1)
int	sendDelayed (cMessage msg, simtime_t delay, cGate outputgate)
int	sendDirect (cMessage msg, cModule mod, const char *inputGateName, int gateIndex=-1)
int	sendDirect (cMessage msg, cModule mod, int inputGateId)
int	sendDirect (cMessage msg, cGate inputGate)
int	sendDirect (cMessage msg, simtime_t propagationDelay, simtime_t duration, cModule mod, const char *inputGateName, int gateIndex=-1)
int	sendDirect (cMessage msg, simtime_t propagationDelay, simtime_t duration, cModule mod, int inputGateId)
int	sendDirect (cMessage msg, simtime_t propagationDelay, simtime_t duration, cGate inputGate)
Self-messages.

int	scheduleAt (simtime_t t, cMessage *msg)
cMessage *	cancelEvent (cMessage *msg)
void	cancelAndDelete (cMessage *msg)
Receiving messages.
These methods may only be invoked from activity()-based simple modules.
cMessage *	receive ()
cMessage *	receive (simtime_t timeout)
Waiting.

void	wait (simtime_t time)
void	waitAndEnqueue (simtime_t time, cQueue *queue)
Stopping the module or the simulation.

void	endSimulation ()
void	halt ()
void	error (const char *format,...) const
Coroutine stack info. Useful only if module uses activity().

virtual bool	hasStackOverflow () const
virtual unsigned	getStackSize () const
virtual unsigned	getStackUsage () const
Protected Member Functions
Hooks for defining module behavior.
Exactly one of activity() and handleMessage() must be redefined by the user to add functionality to the simple module. See the manual for detailed guidance on how use to these two methods. These methods are made protected because they shouldn't be called directly from outside.
virtual void	activity ()
virtual void	handleMessage (cMessage *msg)
Friends
class	cModule
class	cSimulation

Detailed Description

Base class for all simple module classes.

cSimpleModule, although packed with simulation-related functionality, does not do anything useful by itself: one has to subclass from it and redefine one or more virtual member functions to make it do useful work. These functions are:

initialize() is called after OMNeT++ created the module. Multi-stage initialization can be achieved by redefining the initialize(int stage) method instead, and also redefining the numInitStages() const method to return the required number of stages.

One has to redefine handleMessage() to contain the internal logic of the module. handleMessage() is called by the simulation kernel when the module receives a message. (An alternative to handleMessage() is activity(), but activity() is not recommended for serious model development because of scalability and debugging issues. activity() also tends to lead to messy module implementations.)

You can send() messages to other modules, or use scheduleAt()+cancelEvent() to implement delays, timers or timeouts. Messages sent or scheduled (but not cancelled) are delivered to modules via handleMessage(), or, when using activity(), via receive().

The finish() functions are called when the simulation terminates successfully. Typical use of finish() is recording statistics collected during simulation.

Constructor & Destructor Documentation

cSimpleModule::cSimpleModule ( unsigned stacksize = 0 )

Constructor.

Note that module objects should not be created directly, only via their cModuleType objects. See cModule constructor for more info. The stacksize parameter should only be used with simple modules using activity().

cSimpleModule::cSimpleModule	(	const char *	dummy1,
		cModule *	dummy2,
		unsigned	stacksize
	)

COMPATIBILITY.

This constructor is only provided to make it possible to write simple modules that do not use the Module_Class_Members macro and can also be compiled with OMNeT++ versions earlier than 3.2. The first two args are unused in this and later versions.

Member Function Documentation

virtual void cSimpleModule::activity ( ) [protected, virtual]

Should be redefined to contain the module activity function.

For several good reasons, you should prefer handleMessage() to activity(). This default implementation issues an error message (throws cRuntimeError).

void cSimpleModule::cancelAndDelete ( cMessage * msg )

Invokes cancelEvent() on the message (in case it is scheduled), then deletes it.

A NULL pointer is also accepted, then the method does nothing. This method is especially useful in simple module destructors, to dispose of self-messages that the module has allocated.

cMessage* cSimpleModule::cancelEvent ( cMessage * msg )

Removes the given message from the future events.

The message needs to have been sent using the scheduleAt() function. This function can be used to cancel a timer implemented with scheduleAt(). If the message is not currently scheduled, nothing happens.

virtual void cSimpleModule::deleteModule ( ) [virtual]

Deletes the module and all its (dynamically created) submodules.

A running module can also delete itself. When an activity()-based simple module deletes itself from within its activity(), the deleteModule() call will not return (it throws an exception which gets caught by the simulation kernel, and the simulation kernel will delete the module).

When a handleMessage()-based module deletes itself, the deleteModule() returns normally -- then, of course, the code should not try to access data members or functions of the deleted module, an should return as soon as possible.

Reimplemented from cModule.

void cSimpleModule::endSimulation ( )

Causes the whole simulation to stop.

The implementation simply throws a cTerminationException.

virtual void cSimpleModule::forEachChild ( cVisitor * v ) [virtual]

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

See cObject for more details.

Reimplemented from cModule.

virtual unsigned cSimpleModule::getStackSize ( ) const [virtual]

Returns the stack size of the coroutine.

If the module uses handleMessage(), this method always returns 0.

virtual unsigned cSimpleModule::getStackUsage ( ) const [virtual]

Returns the amount of stack actually used by the coroutine.

(Not implemented for every coroutine package - see cCoroutine documentation for more info.) If the module uses handleMessage(), this method always returns 0.

See also:: cCoroutine

void cSimpleModule::halt ( )

May only be invoked from activity()-based simple modules.

Execution of the simple module stops in this call, and any further messages sent to module will cause a runtime error.

virtual void cSimpleModule::handleMessage ( cMessage * msg ) [protected, virtual]

Should be redefined to contain the module's message handling function.

This default implementation issues an error message (throws cRuntimeError).

virtual bool cSimpleModule::hasStackOverflow ( ) const [virtual]

Returns true if there was a stack overflow during execution of the coroutine.

(Not implemented for every coroutine package - see cCoroutine documentation for more info.) If the module uses handleMessage(), this method always returns false.

See also:: cCoroutine

virtual std::string cSimpleModule::info ( ) const [virtual]

Produces a one-line description of the object's contents.

See cObject for more details.

Reimplemented from cModule.

cMessage* cSimpleModule::receive ( simtime_t timeout )

Removes the next message from the event queue and returns a pointer to it.

If there is no message in the event queue, the function waits with t timeout until a message will be available. If the timeout expires and there is still no message in the queue, the function returns NULL.

int cSimpleModule::scheduleAt	(	simtime_t	t,
		cMessage *	msg
	)

Schedules a self-message.

It will be delivered back to the module via receive() or handleMessage() at simulation time t. This method is the way you can implement timers or timeouts. Timers can also be cancelled via cancelEvent() (See below.)

When the message is delivered at the module, you can call msg->isSelfMessage() to tell it apart from messages arriving from other modules. msg->getKind() can be used to further classify it, or of you need to manage an unbounded number of timers, you can set msg->getContextPointer() before scheduling to point to the data structure the message belongs to -- this way you can avoid having to search through lists or other data structures to find out where a just-arrived self-message belongs.

cancelEvent() can be used to cancel the self-message before it arrives. This is useful for implementing timeouts: if the event occurs "in time" (before timeout), the scheduled self-message can be cancelled.

Given a cMessage pointer, you can check whether it is currently scheduled by calling msg->isScheduled(). If it is scheduled, you cannot schedule it again without calling cancelEvent() first. However, after the message was delivered to the module or cancelled, you can schedule it again -- so you can reuse the same message object for timeouts over and over during the whole simulation.

int cSimpleModule::sendDelayed	(	cMessage *	msg,
		simtime_t	delay,
		const char *	gatename,
		int	gateindex = `-1`
	)

Delayed sending.

Sends a message through the gate given with its name and index (if multiple gate) as if it was sent delay seconds later.

int cSimpleModule::sendDelayed	(	cMessage *	msg,
		simtime_t	delay,
		int	gateid
	)

Delayed sending.

Sends a message through the gate given with its index as if it was sent delay seconds later.

int cSimpleModule::sendDirect	(	cMessage *	msg,
		simtime_t	propagationDelay,
		simtime_t	duration,
		cGate *	inputGate
	)

Send a message directly to another module.

If the target gate is further connected (i.e. getNextGate()!=NULL), the message will follow the connections that start at that gate. For example, when sending to an input gate of a compound module, the message will follow the connections inside the compound module.

It is permitted to send to an output gate, which will also cause the message to follow the connections starting at that gate. This can be useful, for example, when several submodules are sending to a single output gate of their parent module.

It is not permitted to send to a gate of a compound module which is not further connected (i.e. getNextGate()==NULL), as this would cause the message to arrive at a compound module.

Also, it is not permitted to send to a gate which is otherwise connected i.e. where getPreviousGate()!=NULL. This means that modules MUST have dedicated gates for receiving via sendDirect(). You cannot have a gate which receives messages via both connections and sendDirect().

When a nonzero duration is given, that signifies the duration of the packet transmission, that is, the time difference between the transmission (or reception) of the start of the packet and that of the end of the packet. The destination module can choose whether it wants the simulation kernel to deliver the packet object to it at the start or at the end of the reception. The default is the latter; the module can change it by calling setDeliverOnReceptionStart() on the final input gate (that is, on inputGate->getPathEndGate()). setDeliverOnReceptionStart() needs to be called in advance, for example in the initialize() method of the module. When a module receives a packet, it can call the isReceptionStart() and getDuration() methods on the packet to find out whether it represents the start or the end of the reception, and the duration of the transmission.

For messages that are not packets (i.e. not subclassed from cPacket), the duration parameter must be zero.

int cSimpleModule::sendDirect	(	cMessage *	msg,
		simtime_t	propagationDelay,
		simtime_t	duration,
		cModule *	mod,
		const char *	inputGateName,
		int	gateIndex = `-1`
	)

Sends a message directly to another module.

See sendDirect(cMessage *, simtime_t, simtime_t, cGate *) for a more detailed description.

int cSimpleModule::sendDirect	(	cMessage *	msg,
		cGate *	inputGate
	)

Sends a message directly to another module, with zero propagation delay and duration.

See sendDirect(cMessage *, simtime_t, simtime_t, cGate *) for a more detailed description.

int cSimpleModule::sendDirect	(	cMessage *	msg,
		cModule *	mod,
		int	inputGateId
	)

Sends a message directly to another module, with zero propagation delay and duration.

See sendDirect(cMessage *, simtime_t, simtime_t, cGate *) for a more detailed description.

int cSimpleModule::sendDirect	(	cMessage *	msg,
		cModule *	mod,
		const char *	inputGateName,
		int	gateIndex = `-1`
	)

Sends a message directly to another module, with zero propagation delay and duration.

See sendDirect(cMessage *, simtime_t, simtime_t, cGate *) for a more detailed description.

bool cSimpleModule::snapshot	(	cObject *	obj = `NULL`,
		const char *	label = `NULL`
	)

To be called from module functions.

Outputs textual information about all objects of the simulation (including the objects created in module functions by the user!) into the snapshot file. The output is detailed enough to be used for debugging the simulation: by regularly calling snapshot(), one can trace how the values of variables, objects changed over the simulation. The arguments: label is a string that will appear in the output file; obj is the object whose inside is of interest. By default, the whole simulation (all modules etc) will be written out.

Tkenv also supports making snapshots manually, from menu.

See also class cWatch and the WATCH() macro.

void cSimpleModule::wait ( simtime_t time )

Waits for the given interval.

(Some other simulators call this functionality hold()). It is intended for use only if you do not expect other messages to arrive at the module during the wait period. To assert this, it throws an exception if a message arrives during the wait.

If you expect to receive messages during the call, you should use waitAndEnqueue() instead.

This function can only be used with activity(), but not with handleMessage().

void cSimpleModule::waitAndEnqueue	(	simtime_t	time,
		cQueue *	queue
	)

Waits for the given interval.

The messages received during the wait period are inserted into the queue passed as argument.

This function can only be used with activity(), but not with handleMessage().

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

csimplemodule.h

cSimpleModule Class Reference [Simulation core classes]

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

cSimpleModule Class Reference
[Simulation core classes]