# cObject Class Reference
[Simulation core classes]

`#include <cobject.h>`

Inheritance diagram for cObject:

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:

- when you insert a cMessage into a cQueue, the cQueue will become the owner of the message, and will set the message's owner to itself.

- a message object can be at one place only at any given time. When you try to insert the same cMessage again into another (or the same) cQueue, you'll get an error message that it's already in a cQueue -- sparing you a sure crash later.

- similarly, if you try to send the same message, you'll get an error message that it cannot be sent because it's still enqueued -- another crash scenario eliminated. Like the previous one, this test is done by checking the owner pointer in cMessage.

- even if you try to delete the message while it's in the queue, you'll get an error message instead of just a crash. This is because cObject destructor asks for the owner's blessing -- but cQueue will protest by throwing an exception.

- when you remove the message from the cQueue, the cQueue will "release" the object; the current module will become the message's "soft" owner, changing the owner pointer in the message object.

- "soft" owner means that now you can send the message object or insert it into another cQueue -- the module as a soft owner will let it go.

- the same mechanism can ensure that when a self-message is currently scheduled (owner is the scheduled-events list) or sent to another module (owner is the other module) you cannot send or schedule it, or insert it into a queue. In short: the ownership mechanism is good to your health.

- when the queue is deleted, it also deletes all objects it contains. (The cQueue always owns all objects inserted into it -- no exception).

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:

- you should use the functions take(), drop() on inserting/removing objects
- you should delete the owned objects in the destructor
- the copy constructor of a container should dup() the owned objects and take() the copies
- if you want to have a class which contains cObject-subclasses as data members: your class (the enclosing object) should own them -- call take() from the constructor and drop() from the destructor.

## Object ownership

cObject * | owner () const
virtual bool | isSoftOwner ()
static cDefaultList * | defaultOwner ()

## Miscellaneous functions.

virtual void | forEachChild (cVisitor *v)
cObject * | findObject (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 cPolymorphic * | dup () const
cObject & | operator= (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:

- cobject.h