cObject Class Reference
[Simulation core classes]

#include <cobject.h>

Inheritance diagram for cObject:

cPolymorphic cAccuracyDetection cArray cBag cChannel cChannelType cClassRegister cDefaultList cEnum cFSM cFunctionType cGate cLinkedList cMessage cMessageHeap cModuleInterface cModuleType cNetworkType cOutVector cPar cQueue cSimulation cStatistic cStructDescriptor cTopology cTransientDetection cWatchBase List of all members.

Detailed Description

Base class for almost all classes in the OMNeT++ library.

It is usually NOT a good idea to subclass your own classes (esp. data storage classes) from cObject, because it is a relatively heavyweight class (about 24 bytes on a 32-bit architecture) with many virtual functions that need to be redefined. You may consider choosing cPolymorphic instead as a base class.

The main areas covered by cObject are:

  1. storage of a name string via name() and setName()
  2. providing a mechanism to recursively traverse all simulation objects (forEachChild() method and cVisitor class). This mechanism constitutes the foundation Tkenv, the simulation GUI.
  3. ownership management, to safeguard against common programming errors. Owner pointer also enables navigating the object tree upwards.

When subclassing cObject, some virtual member functions are expected to be redefined: dup() are mandatory to be redefined, and often you'll want to redefine info() and writeContents() as well.

Ownership management helps OMNeT++ catch common programming errors. As a definition, ownership means the exclusive right and duty to delete owned objects.

cObjects hold a pointer to their owner objects; the owner() method returns this pointer. An example will help to understand how it is used:

The above ownership mechanisms are at work when any cObject-subclass object gets inserted into any cObject-subclass container (cQueue, cArray). Not only obviously container classes act as containers: e.g. cChannel also owns the channel parameters (cPar objects).

Some more details, in case you're writing a class that acts as a container:


Object ownership

cObjectowner () const
virtual bool isSoftOwner ()
static cDefaultListdefaultOwner ()

Miscellaneous functions.

virtual void forEachChild (cVisitor *v)
cObjectfindObject (const char *name, bool deep=true)
static int cmpbyname (cObject *one, cObject *other)

Public Member Functions

Constructors, destructor, assignment.
 cObject (const cObject &obj)
 cObject ()
 cObject (const char *name)
virtual ~cObject ()
virtual cPolymorphicdup () const
cObjectoperator= (const cObject &o)
Handling the name string.
NOTE: "" and NULL are treated liberally: "" is stored as NULL and NULL is returned as "".

virtual void setName (const char *s)
const char * name () const
bool isName (const char *s) const
virtual const char * fullName () const
virtual std::string fullPath () const
virtual const char * fullPath (char *buffer, int buffersize) const
Reflection, support for debugging and snapshots.
virtual void writeContents (std::ostream &os)
Support for parallel execution.
Packs/unpacks object from/to a buffer. These functions are used by parallel execution. These functions should be redefined in all derived classes whose instances are expected to travel across partitions.

virtual void netPack (cCommBuffer *buffer)
virtual void netUnpack (cCommBuffer *buffer)

Static Public Member Functions

Statistics.
static long totalObjectCount ()
static long liveObjectCount ()
static void resetMessageCounters ()

Protected Member Functions

Ownership control.
The following functions are intended to be used by derived container classes to manage ownership of their contained objects. See object description for more info on ownership management.

virtual void take (cObject *obj)
virtual void drop (cObject *obj)
void dropAndDelete (cObject *obj)
Helper functions.
void copyNotSupported () const

Friends

class cDefaultList
class cSimulation
class cMessage


Constructor & Destructor Documentation

cObject::cObject const cObject obj  ) 
 

Copy constructor.

In derived classes, it is usually implemented as {operator=(obj);

cObject::cObject  ) 
 

Create object without a name.

The initial owner of the object will be defaultOwer(); during the simulation, this the 'locals' member of the currently active simple module; otherwise it is the 'defaultList' global variable.

cObject::cObject const char *  name  )  [explicit]
 

Create object with given name.

See cObject() constructor about initial ownership of the object.

virtual cObject::~cObject  )  [virtual]
 

Destructor.

It does the following:

  1. tells the owner that this object is about to be deleted, by calling its ownedObjectDeleted() method with the this pointer. The owner object may protest by throwing an exception.
  2. notifies the environment by calling ev.objectDeleted(this) that the object was deleted. This enables e.g. any open Tkenv inspector windows to be closed.
  3. deallocates object name

Subclasses should delete owned objects here.


Member Function Documentation

static int cObject::cmpbyname cObject one,
cObject other
[static]
 

This function compares to objects by name.

It can be used in a priority queue (class cQueue) as a sorting criterion.

void cObject::copyNotSupported  )  const [protected]
 

Convenience function: throws a cRuntimeError ("copying not supported") stating that assignment, copy constructor and dup() won't work for this object.

You can call this from operator=() if you don't want to implement object copying.

static cDefaultList* cObject::defaultOwner  )  [static]
 

The object that will be the owner of new or dropped (see drop()) objects.

The default owner is set internally, it is usually the simple module processing the current event.

virtual void cObject::drop cObject obj  )  [protected, virtual]
 

Releases ownership of `object'.

Actually it gives ownership of `object' back to its default owner. The function called by the container object when obj is removed from the container -- releases the ownership of the object and hands it over to its default owner.

The obj pointer should not be NULL.

Reimplemented in cDefaultList.

void cObject::dropAndDelete cObject obj  )  [protected]
 

This is a shortcut for the sequence.

   drop(obj);
   delete obj;
 

It is especially useful when writing destructors and assignment operators.

Passing NULL is allowed.

See also:
drop()

virtual cPolymorphic* cObject::dup  )  const [inline, virtual]
 

Duplicates this object.

Duplicates the object and returns a pointer to the new one. Must be redefined in derived classes! In derived classes, it is usually implemented as return new ClassName(*this).

Reimplemented from cPolymorphic.

Reimplemented in cBag, cArray, cChannel, cBasicChannel, cDefaultList, cTDExpandingWindows, cADByStddev, cEnum, cFSM, cGate, cLongHistogram, cDoubleHistogram, cKSplit, cLinkedList, cMessage, cCompoundModule, cMessageHeap, cOutVector, cPacket, cPar, cModulePar, cPSquare, cQueue, cSimpleModule, cSimulation, cStdDev, cWeightedStdDev, cTopology, cModuleInterface, cModuleType, cLinkType, cFunctionType, cClassRegister, cVarHistogram, and cWatchBase.

cObject* cObject::findObject const char *  name,
bool  deep = true
 

Finds the object with the given name.

This function is useful when called on cObject subclasses that are containers. This method finds the object with the given name in a container object and returns a pointer to it or NULL if the object hasn't been found. If deep is false, only objects directly contained will be searched, otherwise the function searches the whole subtree for the object. It uses the forEachChild() mechanism.

Do not use it for finding submodules! See cModule::moduleByRelativePath().

virtual void cObject::forEachChild cVisitor v  )  [virtual]
 

Enables traversing the object tree, performing some operation on each object.

The operation is encapsulated in the particular subclass of cVisitor.

This method should be redefined in every subclass to call v->visit(obj) for every obj object contained.

Reimplemented in cArray, cChannel, cBasicChannel, cDefaultList, cGate, cMessage, cModule, cMessageHeap, cPar, cQueue, cSimpleModule, and cSimulation.

virtual const char* cObject::fullName  )  const [inline, virtual]
 

Returns a name that includes the object 'index' (e.g.

in a module vector), like "modem[5]". To be redefined in descendants. E.g., see cModule::fullName().

Reimplemented from cPolymorphic.

Reimplemented in cGate, and cModule.

virtual const char* cObject::fullPath char *  buffer,
int  buffersize
const [virtual]
 

Returns the full path of the object in the object hierarchy, like "comp.modem[5].baud-rate".

The result is placed into the buffer passed.

Reimplemented in cGate, cModule, cModulePar, and cSimulation.

virtual std::string cObject::fullPath  )  const [virtual]
 

Returns the full path of the object in the object hierarchy, like "comp.modem[5].baud-rate".

NOTE: the returned pointer points into a static buffer, which is overwritten by subsequent calls!

Reimplemented from cPolymorphic.

Reimplemented in cGate, cModule, cModulePar, and cSimulation.

bool cObject::isName const char *  s  )  const [inline]
 

Returns true if the object's name is identical to the string passed.

virtual bool cObject::isSoftOwner  )  [inline, virtual]
 

Returns false, which means if this A object is the owner of some other object B, then B cannot be taken by any other object (see take()) -- an error will be raised saying the object is owned by A.

This method only returns true in cDefaultList.

Reimplemented in cDefaultList.

static long cObject::liveObjectCount  )  [inline, static]
 

Returns the number of objects that currently exist in the program.

The counter is incremented by cObject constructor and decremented by the destructor. May be useful for profiling or debugging memory leaks.

const char* cObject::name  )  const [inline]
 

Returns pointer to the object's name.

The function never returns NULL; rather, it returns ptr to "".

virtual void cObject::netPack cCommBuffer buffer  )  [virtual]
 

Serializes the object into a buffer.

Reimplemented in cBag, cArray, cChannel, cBasicChannel, cDefaultList, cDensityEstBase, cFSM, cHistogramBase, cEqdHistogramBase, cKSplit, cLinkedList, cMessage, cOutVector, cPacket, cPar, cPSquare, cQueue, cStatistic, cStdDev, cWeightedStdDev, cTopology, and cVarHistogram.

virtual void cObject::netUnpack cCommBuffer buffer  )  [virtual]
 

Deserializes the object from a buffer.

Reimplemented in cBag, cArray, cChannel, cBasicChannel, cDefaultList, cDensityEstBase, cFSM, cHistogramBase, cEqdHistogramBase, cKSplit, cLinkedList, cMessage, cOutVector, cPacket, cPar, cPSquare, cQueue, cStatistic, cStdDev, cWeightedStdDev, cTopology, and cVarHistogram.

cObject& cObject::operator= const cObject o  ) 
 

The assignment operator.

Derived classes should contain similar methods (cClassName& cClassName::operator=(cClassName&)).

Assigment copies the contents of the object EXCEPT for the name string. If you want to copy the name string, you can do it by hand: setName(o.name()).

Ownership of the object is not affected by assigments.

cObject* cObject::owner  )  const [inline]
 

Returns pointer to the owner of the object.

static void cObject::resetMessageCounters  )  [inline, static]
 

Reset counters used by totalObjectCount() and liveObjectCount().

(Note that liveObjectCount() may go negative after a reset call.)

Reimplemented in cMessage.

virtual void cObject::setName const char *  s  )  [virtual]
 

Sets object's name.

The object creates its own copy of the string. NULL pointer may also be passed.

Reimplemented in cGate, cModule, and cOutVector.

virtual void cObject::take cObject obj  )  [protected, virtual]
 

Makes this object the owner of 'object'.

The function called by the container object when it takes ownership of the obj object that is inserted into it.

The obj pointer should not be NULL.

Reimplemented in cDefaultList.

static long cObject::totalObjectCount  )  [inline, static]
 

Returns the total number of objects created since the start of the program (or since the last reset).

The counter is incremented by cObject constructor. Counter is signed to make it easier to detect if it overflows during very long simulation runs. May be useful for profiling or debugging memory leaks.

virtual void cObject::writeContents std::ostream &  os  )  [virtual]
 

This function is indirectly invoked by snapshot().

It is expected to write textual information about the object and other objects it contains to the stream.

This default version (cObject::writeContents()) prints detailedInfo() and uses forEachChild() to call info() for contained objects. It only needs to be redefined if this behaviour is should be customized.

Reimplemented in cChannel, cBasicChannel, cDensityEstBase, cFSM, cGate, cKSplit, cMessage, cPar, cPSquare, cSimulation, and cStdDev.


The documentation for this class was generated from the following file:
Generated on Sat Oct 21 17:47:57 2006 for OMNeT++/OMNEST Simulation Library by  doxygen 1.4.6