Main Page Modules Class Hierarchy Compound List File List Compound Members

# cSimpleModule Class Reference

`#include <cmodule.h>`

Inheritance diagram for cSimpleModule::

List of all members.

## Public Methods

Constructors, destructor, assignment.
| cSimpleModule (const cSimpleModule &mod)
| cSimpleModule (const char *name, cModule *parentmod, unsigned stk)
virtual | ~cSimpleModule ()
cSimpleModule& | operator= (const cSimpleModule &mod)
Redefined cObject functions.
virtual cObject* | dup () const
virtual void | info (char *buf)
virtual void | forEach (ForeachFunc f)
Redefined cModule functions.
virtual void | setId (int n)
virtual bool | isSimple () const
virtual bool | callInitialize (int stage)
virtual void | callFinish ()
virtual void | scheduleStart (simtime_t t)
virtual void | deleteModule ()
Information about the module.
bool | usesActivity () const
Simulation time.
simtime_t | simTime () const
Debugging aids.
void | setPhase (const char *phase)
const char* | phase () const
bool | snapshot (cObject *obj=&simulation, const char *label=NULL)
void | breakpoint (const char *label)
void | pause (const char *phase=NULL)
Message sending.
int | send (cMessage *msg, int gateid)
int | send (cMessage *msg, const char *gatename, int sn=-1)
int | send (cMessage *msg, cGate *outputgate)
int | sendDelayed (cMessage *msg, double delay, int gateid)
int | sendDelayed (cMessage *msg, double delay, const char *gatename, int sn=-1)
int | sendDelayed (cMessage *msg, double delay, cGate *outputgate)
int | sendDirect (cMessage *msg, double delay, cModule *mod, int inputgateid)
int | sendDirect (cMessage *msg, double delay, cModule *mod, const char *inputgatename, int sn=-1)
int | sendDirect (cMessage *msg, double delay, cGate *inputgate)
Self-messages.
int | scheduleAt (simtime_t t, cMessage *msg)
cMessage* | cancelEvent (cMessage *msg)
Parallel simulation.
void | syncpoint (simtime_t t, int gateid)
void | syncpoint (simtime_t t, const char *gatename, int sn=-1)
void | cancelSyncpoint (simtime_t t, int gateid)
void | cancelSyncpoint (simtime_t t, const char *gatename, int sn=-1)
Receiving messages.
These functions can only be used with activity(), but not with handleMessage().
bool | isThereMessage () const
cMessage* | receive ()
cMessage* | receive (simtime_t timeout)
cMessage* | receiveOn (const char *gatename, int sn=-1, simtime_t timeout=MAXTIME)
cMessage* | receiveOn (int gateid, simtime_t timeout=MAXTIME)
cMessage* | receiveNew ()
cMessage* | receiveNew (simtime_t timeout)
cMessage* | receiveNewOn (const char *gatename, int sn=-1, simtime_t timeout=MAXTIME)
cMessage* | receiveNewOn (int gateid, simtime_t timeout=MAXTIME)
Waiting.
void | wait (simtime_t time)
void | waitAndEnqueue (simtime_t time, cQueue *queue)
Stopping the module or the simulation.
void | end ()
void | endSimulation ()
void | error (const char *fmt,...) const
Statistics collection
void | recordScalar (const char *name, double value)
void | recordScalar (const char *name, const char *text)
void | recordStats (const char *name, cStatistic *stats)
virtual bool | stackOverflow () const
virtual unsigned | stackSize () const
virtual unsigned | stackUsage () const
Miscellaneous.
void* | memAlloc (size_t m)
void | memFree (void *&p)
int | moduleState () const

## Public Attributes

cQueue | putAsideQueue

## Protected Methods

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)

## Detailed Description

cSimpleModule is the base class for all simple module classes. cSimpleModule, although stuffed with simulation-related functionality, doesn't do anything useful by itself: one has to redefine one or more virtual member functions to make it do useful work:

- void initialize()
- void activity()
- void handleMessage(cMessage *msg)
- void finish()

initialize() is called after OMNeT++ created the module.

One has to redefine either activity() or handleMessage() to contain the internal logic of the module. activity() and handleMessage() implement different event processing strategies: activity() is a coroutine-based solution which implements the process-interaction approach (coroutines are non-preemptive [cooperative] threads). handleMessage() is a method that is called by the simulation kernel when the module receives a message.

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

The activity() functions run as coroutines during simulation. Coroutines are brought to cSimpleModule from the cCoroutine base class.

## Constructor & Destructor Documentation

cSimpleModule::cSimpleModule ( | const cSimpleModule & mod )

| Copy constructor.

cSimpleModule::cSimpleModule ( | const char * name,
| cModule * parentmod,
| unsigned stk )

| Constructor. Note that module objects should not be created directly, only via their cModuleType objects. See cModule constructor for more info.

cSimpleModule::~cSimpleModule ( | )`[virtual]`

| Destructor.

## Member Function Documentation

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

| Should be redefined to contain the module activity function. This default implementation issues an error message (throws cException).

void cSimpleModule::breakpoint ( | const char * label )

| Specifies a breakpoint. During simulation, if execution gets to a breakpoint() call (and breakpoints are active etc.), the simulation will be stopped, if the user interface can handle breakpoints.

void cSimpleModule::callFinish ( | )`[virtual]`

| Calls finish() in the context of this module. Reimplemented from cModule.

bool cSimpleModule::callInitialize ( | int stage )`[virtual]`

| Calls initialize(int stage) in the context of this module. It does a single stage of initialization, and returns `true` if more stages are required. Reimplemented from cModule.

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

void cSimpleModule::cancelSyncpoint ( | simtime_t t,
| const char * gatename,
| int sn = -1 )

| Used with parallel execution: cancel a synchronization point set by a syncpoint() call.

void cSimpleModule::cancelSyncpoint ( | simtime_t t,
| int gateid )

| Used with parallel execution: cancel a synchronization point set by a syncpoint() call.

void cSimpleModule::deleteModule ( | )`[virtual]`

| Deletes a dynamically created module. A running module can also delete itself. Reimplemented from cModule.

cObject * cSimpleModule::dup ( | ) const`[inline, virtual]`

| Creates and returns an exact copy of this object. See cObject for more details. Reimplemented from cObject.

void cSimpleModule::end ( | )

Ends the run of the simple module. The simulation is not stopped (unless this is the last running module.) The implementation simply throws a cEndModuleException.

Note that end() does NOT delete the module; its state is simply set to Ended and it won't take part in further simulation. If you also want to delete the module, use deleteModule(); however, this implies that the module's finish() method won't be called at the end of the simulation.

void cSimpleModule::endSimulation ( | )

| Causes the whole simulation to stop. The implementation simply throws a cTerminationException.

void cSimpleModule::error ( | const char * fmt,
| ... ) const

| DEPRECATED. Equivalent to `throw new cException( ...same argument list...)`.

void cSimpleModule::forEach ( | ForeachFunc f )`[virtual]`

| Call the passed function for each contained object. See cObject for more details. Reimplemented from cModule.

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

void cSimpleModule::info ( | char * buf )`[virtual]`

| Produces a one-line description of object contents into the buffer passed as argument. See cObject for more details. Reimplemented from cObject.

bool cSimpleModule::isSimple ( | ) const`[inline, virtual]`

| Returns true. Reimplemented from cModule.

bool cSimpleModule::isThereMessage ( | ) const

| DEPRECATED. Tells if the next message in the event queue is for the same module and has the same arrival time. (Returns true only if two or more messages arrived to the module at the same time.)

void * cSimpleModule::memAlloc ( | size_t m )

Dynamic memory allocation. This function should be used instead of the global malloc() from inside the module function (activity()), if deallocation by the simple module constructor is not provided.

Dynamic allocations are discouraged in general unless you put the pointer into the class declaration of the simple module class and provide a proper destructor. Or, you can use container classes (cArray, cQueue)!

void cSimpleModule::memFree ( | void *& p )

| Frees a memory block reserved with the malloc() described above and NULLs the pointer.

int cSimpleModule::moduleState ( | ) const`[inline]`

| Returns module state.

cSimpleModule & cSimpleModule::operator= ( | const cSimpleModule & mod )

| Assignment operator. The name member doesn't get copied; see cObject's operator=() for more details.

void cSimpleModule::pause ( | const char * phase = NULL )

Sets phase string and temporarily yield control to the user interface. If the user interface supports step-by-step execution, one can stop execution at each receive() call of the module function and examine the objects, variables, etc. If the state of simulation between receive() calls is also of interest, one can use pause() calls. The string argument (if given) sets the phase string, so pause("here") is the same as setPhase("here"); pause().

const char * cSimpleModule::phase ( | ) const`[inline]`

| DEPRECATED. Returns pointer to the current phase string.

cMessage * cSimpleModule::receive ( | simtime_t timeout )

| Returns the first message from the put-aside queue or, if it is empty, calls receiveNew() to return a message from the event queue with the given timeout. Note that the arrival time of the message returned by receive() can be earlier than the current simulation time.

cMessage * cSimpleModule::receive ( | )

| Receives a message from the put-aside queue or the FES.

cMessage * cSimpleModule::receiveNew ( | simtime_t timeout )

Removes the next message from the event queue and returns a pointer to it. Ignores put-aside queue. 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.

IMPORTANT: This function should not be used. As putAsideQueue is deprecated, it will be removed at some point in the future. This means that then the receive() method will act exactly as this one, and this method will no longer be needed. See the API-doc on putAsideQueue, wait() and waitAndEnqueue() for more explanation.

cMessage * cSimpleModule::receiveNew ( | )

Remove the next message from the event queue and return a pointer to it. Ignores put-aside queue.

IMPORTANT: This function should not be used. As putAsideQueue is deprecated, it will be removed at some point in the future. This means that then the receive() method will act exactly as this one, and this method will no longer be needed. See the API-doc on putAsideQueue, wait() and waitAndEnqueue() for more explanation.

cMessage * cSimpleModule::receiveNewOn ( | int gateid,
| simtime_t timeout = MAXTIME )

Same as the previous function except that the gate must be specified with its index in the gate array. Using this function instead the previous one may speed up the simulation if the function is called frequently.

IMPORTANT: This function should not be used. As putAsideQueue is deprecated, it will be removed at some point in the future. This means that then the receiveOn() method will act exactly as this one, and this method will no longer be needed. See the API-doc on putAsideQueue, wait() and waitAndEnqueue() for more explanation.

cMessage * cSimpleModule::receiveNewOn ( | const char * gatename,
| int sn = -1,
| simtime_t timeout = MAXTIME )

The same as receiveNew(), except that it returns the next message that arrives on the gate specified with its name and index. All messages received meanwhile are inserted into the put-aside queue. If the timeout expires and there is still no such message in the queue, the function returns NULL.

In order to process messages that may have been put in the put-aside queue, the user is expected to call receive() or receiveOn(), or to examine the put-aside queue directly sometime.

IMPORTANT: This function should not be used. As putAsideQueue is deprecated, it will be removed at some point in the future. This means that then the receiveOn() method will act exactly as this one, and this method will no longer be needed. See the API-doc on putAsideQueue, wait() and waitAndEnqueue() for more explanation.

cMessage * cSimpleModule::receiveOn ( | int gateid,
| simtime_t timeout = MAXTIME )

Same as the previous function except that the gate must be specified with its index in the gate array. Using this function instead the previous one may speed up the simulation if the function is called frequently.

IMPORTANT: The put-aside queue has been deprecated, and the semantics of this function will be changed in the future. It will be intended for use only if you do not expect other messages to arrive at the module on other gates than the specified one. To assert this, it will throw an exception if an inappropriate message arrives, as it will probably signal a logic error in the model. On the other hand, if you do expect to receive other messages during the call, you should not use receiveOn() but implement similar functionality using a loop (for() or while()) and receive(), which will make your intent more conspicuous to the reader of your source code. See the API-doc on putAsideQueue for more explanation.

cMessage * cSimpleModule::receiveOn ( | const char * gatename,
| int sn = -1,
| simtime_t timeout = MAXTIME )

Scans the put-aside queue for the first message that has arrived on the gate specified with its name and index. If there is no such message in the put-aside queue, calls receiveNew() to return a message from the event queue with the given timeout. Note that the arrival time of the message returned by receive() can be earlier than the current simulation time.

IMPORTANT: The put-aside queue has been deprecated, and the semantics of this function will be changed in the future. It will be intended for use only if you do not expect other messages to arrive at the module on other gates than the specified one. To assert this, it will throw an exception if an inappropriate message arrives, as it will probably signal a logic error in the model. On the other hand, if you do expect to receive other messages during the call, you should not use receiveOn() but implement similar functionality using a loop (for() or while()) and receive(), which will make your intent more conspicuous to the reader of your source code. See the API-doc on putAsideQueue for more explanation.

void cSimpleModule::recordScalar ( | const char * name,
| const char * text )

| Records a string into the scalar result file.

void cSimpleModule::recordScalar ( | const char * name,
| double value )

| Records a double into the scalar result file.

void cSimpleModule::recordStats ( | const char * name,
| cStatistic * stats )

| Records a statistics object into the scalar result file.

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

| Schedules a self-message. Receive() will return the message at t simulation time.

void cSimpleModule::scheduleStart ( | simtime_t t )`[virtual]`

| Creates a starting message for the module. Reimplemented from cModule.

int cSimpleModule::send ( | cMessage * msg,
| cGate * outputgate )

| Sends a message through the gate given with its pointer.

int cSimpleModule::send ( | cMessage * msg,
| const char * gatename,
| int sn = -1 )

| Sends a message through the gate given with its name and index (if multiple gate).

int cSimpleModule::send ( | cMessage * msg,
| int gateid )

| Sends a message through the gate given with its ID.

int cSimpleModule::sendDelayed ( | cMessage * msg,
| double delay,
| cGate * outputgate )

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

int cSimpleModule::sendDelayed ( | cMessage * msg,
| double delay,
| const char * gatename,
| int sn = -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,
| double 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,
| double delay,
| cGate * inputgate )

| Sends a message directly to another module (to an input gate).

int cSimpleModule::sendDirect ( | cMessage * msg,
| double delay,
| cModule * mod,
| const char * inputgatename,
| int sn = -1 )

| Send a message directly to another module (to an input gate).

int cSimpleModule::sendDirect ( | cMessage * msg,
| double delay,
| cModule * mod,
| int inputgateid )

| Send a message directly to another module (to an input gate).

void cSimpleModule::setId ( | int n )`[virtual]`

| FIXME: redefined cModule functions: Reimplemented from cModule.

void cSimpleModule::setPhase ( | const char * phase )`[inline]`

| DEPRECATED. Sets the phase string which can be displayed as some kind of status. The module creates its own copy of the string.

simtime_t cSimpleModule::simTime ( | ) const

| Returns the current simulation time (that is, the arrival time of the last message returned by a receiveNew() call).

bool cSimpleModule::snapshot ( | cObject * obj = &simulation,
| 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.

bool cSimpleModule::stackOverflow ( | ) 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

unsigned cSimpleModule::stackSize ( | ) const`[virtual]`

| Returns the stack size of the coroutine. If the module uses handleMessage(), this method always returns 0.

unsigned cSimpleModule::stackUsage ( | ) 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::syncpoint ( | simtime_t t,
| const char * gatename,
| int sn = -1 )

| Used with parallel execution: synchronize with receiver segment. Blocks receiver at t until a message arrives.

void cSimpleModule::syncpoint ( | simtime_t t,
| int gateid )

| Used with parallel execution: synchronize with receiver segment. Blocks receiver at t until a message arrives.

bool cSimpleModule::usesActivity ( | ) const`[inline]`

| Returns event handling scheme.

void cSimpleModule::wait ( | simtime_t time )

Waits for the given interval. (Some other simulators call this functionality hold()). The messages received meanwhile are inserted into the put-aside queue, but if you expect to receive messages during the call, you should use the waitAndEnqueue() method instead (see the following note).

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

IMPORTANT: The put-aside queue has been deprecated, and the semantics of this function will be changed in the future. It will be intended for use only if you do not expect other messages to arrive at the module during the wait period. To assert this, it will throw an exception if a message arrives during the wait, as it will probably signal a logic error in the model. On the other hand, if you do expect to receive messages during the call, you should use waitAndEnqueue(), which makes this assumption much more conspicuous to the reader of your source code than the old wait() method with its implicit putAsideQueue would. See the API-doc on putAsideQueue for more explanation.

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

## Member Data Documentation

cQueue cSimpleModule::putAsideQueue

DEPRECATED. putAsideQueue will be removed at some point in the future, and this will affect the message receiving functions. Details below.

putAsideQueue is used implicitly by the methods wait(), receiveOn() and receiveNewOn() to insert messages that arrive during the wait period or not on the specified gate. The receive() functions looked first on the putAsideQueue and only then at the future events.

As practice has shown, the purpose of the putAsideQueue was very often misunderstood, and its implicit use by wait() and the message receiving functions was highly error-prone. It will be removed at some point in the future. Be prepared: use wait() and receiveOn() if you do not expect other messages to arrive at the module; use waitAndEnqueue() where you mean it; do not use the receiveNew..() functions as they will be made redundant when putAsideQueue goes away.

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

- cmodule.h