cSimpleModule Class Reference
[Simulation core classes]

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

#include <csimplemodule.h>

Inheritance diagram for cSimpleModule:
cModule cComponent cDefaultList cNoncopyableOwnedObject cOwnedObject noncopyable cNamedObject cObject

List of all members.

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)
cMessagecancelEvent (cMessage *msg)
void cancelAndDelete (cMessage *msg)
Receiving messages.

These methods may only be invoked from activity()-based simple modules.

cMessagereceive ()
cMessagereceive (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:
Generated on Mon Jul 14 12:57:26 2014 for OMNeT++ Simulation Library by  doxygen 1.6.3