Main Page Modules Class Hierarchy Compound List File List Compound Members

# cObject Class Reference

`#include <cobject.h>`

Inheritance diagram for cObject::

List of all members.

## Miscellaneous functions.

virtual void | forEach (ForeachFunc f)
char | storage () const
void* | operator new (size_t m)
cObject* | findObject (const char *name, bool deep=true)
int | cmpbyname (cObject *one, cObject *other)

## Public Methods

Constructors, destructor, assignment.
| cObject (const cObject &obj)
| cObject ()
| cObject (const char *name)
virtual | ~cObject ()
virtual cObject* | dup () const
void | destruct ()
cObject& | operator= (const cObject &o)
Handling the name string.
NOTE: "" and NULL are treated liberally: "" is stored as NULL and NULL is returned as "".
void | setName (const char *s)
const char* | name () const
bool | isName (const char *s) const
virtual const char* | fullName () const
virtual const char* | fullPath () const
virtual const char* | fullPath (char *buffer, int buffersize) const
Object ownership. See object description for more info on ownership management.
cObject* | owner () const
void | setOwner (cObject *newowner)
virtual cObject* | defaultOwner () const
Ownership control flag.
The ownership control flag is to be used by derived container classes. If the flag is set, the container should take() any object that is inserted into it.
void | takeOwnership (bool tk)
bool | takeOwnership () const
Reflection, support for debugging and snapshots.
virtual const char* | className () const
virtual void | info (char *buf)
virtual void | writeTo (ostream &os)
virtual void | writeContents (ostream &os)
Support for parallel execution.
Packs/unpacks object from/to PVM or MPI send buffer. These functions are used by the simulation kernel for parallel execution. These functions should be redefined in all derived classes whose instances are expected to travel across segments in a parallel distribution run.
virtual int | netPack ()
virtual int | netUnpack ()

## Protected Methods

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.
void | take (cObject *object)
void | drop (cObject *object)
void | discard (cObject *object)
Helper functions.
void | copyNotSupported () const

## Detailed Description

cObject is the base class for almost all classes in the OMNeT++ library.

Containing 5 pointers and 2 flags as data and several virtual functions, cObject is a relatively heavyweight object for a base class. If you need to create a new class, you may or may not choose starting from cObject as base class.

The two main areas covered by cObject are:

1. basic reflection (name string via name() and setName(); className())
2. ownership management

cObject provides a name member (a dynamically allocated string).

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

OMNeT++ provides a fairly complex memory management via the object ownership mechanism. It usually works well without you paying attention, but it generally helps to understand how it works.

Rule 1: Ownership means exclusive right and duty to delete owned objects. The owner of any 'o' object is returned by o->owner(), and can be changed with o->setOwner(). The destructor of cObject deletes (via discard()) all owned objects, and so do all classes derived from cObject.

Ownership internally works via 4 pointers as cObject data members: ownerp points to owner object; prevp/nextp points to previous/next object in owner's owned objects list; firstchildp points to first owned object. The setOwner() method works on the ownerp, prevp and nextp pointers.

The object ownership mechanism is competely independent of the way containers (cArray, cQueue) hold contained objects. For example, a cQueue may actually own all, some, or none of the object in the queue. (Container classes use mechanisms independent of firstchildp to store contained objects; e.g., cArray uses an array, while cQueue uses a separate list). Exception is cHead, which displays owned objects as contents.

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

Ownership: By default, the object is assumed to have been created by the currently active simple module, so the owner will be the "local objects" list of that module. (More precisely, the owner will be set using `setOwner(defaultOwner())`, and cObject::defaultOwner() returns simulation.localList(), an alias to the currently active simple module's local objects list. Note: Overriding defaultOwner() won't change this because virtual functions are only effective after constructor has completed. If you want to change the initial owner in a derived class, you have to call setOwner() directly in the derived class' constructor.)

If there is no active simple module (we're not in a simulation), the owner will be NULL.

cObject::cObject ( | const char * name )`[explicit]`

| Create object with given name. See cObject() constructor about initial ownership of the object.

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

Destructor. It does the following:

1. notifies the environment by calling ev.objectDeleted(this) that the object was deleted. This enables any open inspector windows to be closed.
2. removes the object from the owner object's list (setOwner(NULL))
3. deletes all owned objects by calling their discard() method
4. deallocates object name

## Member Function Documentation

const char * cObject::className ( | ) const`[virtual]`

| Returns a pointer to the class name string. Since OMNeT++ 2.3, this method is implemented once here in cObject, using typeid (C+ RTTI), and it no longer needs to be redefined in each class.

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]`

| throws a cException ("copying not supported") stating that assignment, copy constructor and dup() won't work for this object. This is a convenience function to be called from the operator=() method of cObject subclasses that do not wish to implement object copying.

cObject * cObject::defaultOwner ( | ) const`[virtual]`

| Returns pointer to the default owner of the object. This function is used by the drop() member function.

void cObject::destruct ( | )`[inline]`

| Direct call to the virtual destructor. This function is used internally at cleanup (e.g. at the end of the simulation) for disposing of objects left on module stacks of activity() modules.

void cObject::discard ( | cObject * object )`[inline, protected]`

Disposes of `object'; it MUST be owned by this object. The function is called when the container object has to delete the contained object obj. It the object was dynamically allocated (by operator new), it is deleted, otherwise (e.g., if it is a global or a local variable) it is just removed from the ownership hierarchy.

Implementation:

         if(obj->storage()=='D')
             delete obj;
         else
             obj->setOwner(NULL);

void cObject::drop ( | cObject * object )`[inline, protected]`

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.

Implementation:

         obj->setOwner( obj->defaultOwner() );

cObject * 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 cObject(*this)`.

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

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

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

Call f for each contained object.

Makes sense with container objects derived from cObject. Calls the f function recursively for each object contained in this object.

The passed function is called for each object twice: once on entering and once on leaving the object. In addition, after the first ('entering') call to the function, it signals with its return value whether it wants to go deeper in the contained objects or not.

Functions passed to forEach() will use static variables to store other necessary information. (Yes, this limits their recursive use :-( ).

forEach() takes a function do_fn (of ForeachFunc type) with 2 arguments: a cObject* and a bool. First, forEach() should call do_fn(this,true) to inform the function about entering the object. Then, if this call returned true, it must call forEach(do_fn) for every contained object. Finally, it must call do_fn(this,false) to let do_fn know that there's no more contained object.

Functions using forEach() work in the following way: they call do_fn(NULL, false, <additional args>) to initialize the static variables inside the function with the additional args passed. Then they call forEach(do_fn) for the given object. Finally, read the results by calling do_fn(NULL, false, <additional args>), where additional args can be pointers where the result should be stored. ForeachFuncs mustn't call themselves recursively!

I know the foreach() mechanism described here is a bit weird. Actually I wrote it a long ago, and changing it now would take quite some work. And after all, it works..

Reimplemented in cArray, cChannel, cSimpleChannel, cGate, cHead, cMessage, cModule, cSimpleModule, cMessageHeap, cPar, cQueue, and cSimulation.

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 in cGate, and cModule.

const char * cObject::fullPath ( | char * buffer,
| int bufsize ) 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.

const char * 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 in cGate, cModule, cModulePar, and cSimulation.

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

| Produces a one-line description of object into `buf'. This function is used by the graphical user interface (TkEnv). See also Functions supporting snapshots. Reimplemented in cBag, cArray, cChannel, cSimpleChannel, cEnum, cFSM, cGate, cLinkedList, cMessage, cSimpleModule, cCompoundModule, cMessageHeap, cOutVector, cPacket, cPar, cQueue, cStdDev, cTopology, and cWatch.

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

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

const char * cObject::name ( | ) const`[inline]`

| Returns pointer to the object's name. The function never returns NULL; rather, it returns ptr to "".

int cObject::netPack ( | )`[virtual]`

Serializes the object into a PVM or MPI send buffer. In OMNeT++'s PVM interface, this method makes calls pvm_pkint(), etc.

Reimplemented in cBag, cArray, cChannel, cSimpleChannel, cDensityEstBase, cTransientDetection, cAccuracyDetection, cFSM, cHistogramBase, cEqdHistogramBase, cLongHistogram, cDoubleHistogram, cKSplit, cLinkedList, cMessage, cPacket, cPar, cPSquare, cQueue, cStatistic, cStdDev, cWeightedStdDev, cTopology, and cVarHistogram.

int cObject::netUnpack ( | )`[virtual]`

Deserializes the object from a PVM or MPI receive buffer. In OMNeT++'s PVM interface, this method makes calls pvm_upkint(), etc.

Reimplemented in cBag, cArray, cChannel, cSimpleChannel, cDensityEstBase, cTransientDetection, cAccuracyDetection, cFSM, cHistogramBase, cEqdHistogramBase, cLongHistogram, cDoubleHistogram, cKSplit, cLinkedList, cMessage, cPacket, cPar, cPSquare, cQueue, cStatistic, cStdDev, cWeightedStdDev, cTopology, and cVarHistogram.

void * cObject::operator new ( | size_t m )

cObject's operator new does more than the global new(). It cooperates with cObject's constructor to determine the storage class of the object (static, auto or dynamic).

See also:
  storage()

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.

void cObject::setName ( | const char * name )`[inline]`

| Sets object's name. The object creates its own copy of the string. NULL pointer may also be passed. Reimplemented in cOutVector.

void cObject::setOwner ( | cObject * newowner )

Sets the owner of the object. NULL is legal a legal value and means that no object will own this one (ownerp=NULL).

See also:
  defaultOwner()

char cObject::storage ( | ) const`[inline]`

| Returns the storage class of the object. The return value is one of the characters S/A/D which stand for static, auto and dynamic, respectively. (The storage class is determined by the constructor, with some help from cObject's operator new().)

void cObject::take ( | cObject * object )`[inline, protected]`

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.

Implementation:

         obj->setOwner( this );

bool cObject::takeOwnership ( | ) const`[inline]`

| Returns the flag which determines whether the container object should automatically take ownership of the objects that are inserted into it.

void cObject::takeOwnership ( | bool tk )`[inline]`

| Sets the flag which determines whether the container object should automatically take ownership of the objects that are inserted into it.

void cObject::writeContents ( | ostream & os )`[virtual]`

This function is called internally by writeTo(). It is expected to write textual information about the object and other objects it contains to the stream. The default version (cObject::writeContents()) uses forEach() to call info() for contained objects. Redefine as needed.

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

void cObject::writeTo ( | ostream & os )`[virtual]`

| This function is called internally by cSimpleModule::snapshot(). It writes out info about the object into the stream. Relies on writeContents(). writeTo() does not need to be redefined.

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

- cobject.h