Main Page   Modules   Class Hierarchy   Compound List   File List   Compound Members  

cObject Class Reference

#include <cobject.h>

Inheritance diagram for cObject::

cAccuracyDetection cArray cBag cClassRegister cEnum cFSM cFunctionType cGate cHead cInspectorFactory cLinkedList cLinkType cMessage cMessageHeap cModule cModuleInterface cModuleType cNetworkType cOutVector cPar cQueue cSimulation cStatistic cStructDescriptor cTopology cTransientDetection cWatch List of all members.

Miscellaneous functions.

virtual void forEach (ForeachFunc f)
char storage () const
void* operator new (size_t m)
void deleteChildren ()
void destructChildren ()
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)
 cObject (const char *name, cObject *ownerobj)
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.
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 TInspector* inspector (int type, void *data)
virtual const char* inspectorFactoryName () const
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.

void take (cObject *object)
void drop (cObject *object)
void dealloc (cObject *object)
Helper functions.
void copyNotSupported () const

Detailed Description

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

cObject provides a name member (a dynamically allocated string) and a number of virtual functions. These functions either provide a default behavior (mostly good for all derived classes), or they are expected to be redefined in all derived classes.

Some of the features provided by cObject:


Constructor & Destructor Documentation

cObject::cObject ( const cObject & obj )
 

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

cObject::cObject ( )
 

Create object with no name and default owner.

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

Create object with given name and default owner.

cObject::cObject ( const char * name,
cObject * ownerobj )
 

Create object with given name and specified owner. The owner will be the h object (if the pointer is not NULL), that is, the constructor contains a setOwner(h) call.

cObject::~cObject ( ) [virtual]
 

Virtual destructor. Deletes the name and notifies the user interface that the object has been destructed.


Member Function Documentation

const char * cObject::className ( ) const [inline, virtual]
 

Returns a pointer to the class name string, "cObject". In derived classes, usual implementation is {return "classname";}.

Reimplemented in cBag, cArray, cDensityEstBase, cTransientDetection, cAccuracyDetection, cTDExpandingWindows, cADByStddev, cEnum, cFSM, cGate, cHead, cHistogramBase, cEqdHistogramBase, cLongHistogram, cDoubleHistogram, cKSplit, cLinkedList, cMessage, cModule, cSimpleModule, cCompoundModule, cMessageHeap, cNetMod, cOutVector, cPacket, cPar, cModulePar, cPSquare, cQueue, cSimulation, cStatistic, cStdDev, cWeightedStdDev, cStructDescriptor, cTopology, cModuleInterface, cModuleType, cLinkType, cNetworkType, cFunctionType, cClassRegister, cInspectorFactory, cVarHistogram, and cWatch.

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]
 

Raises an error 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.

void cObject::dealloc ( 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 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);
 

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

Returns pointer to the default owner of the object. This function is used by the setOwner() and drop() member functions. drop() is used in container classes derived from cObject.

void cObject::deleteChildren ( )
 

Deletes all dynamic objects (those allocated on the heap) whose owner is this object. Other owned objects are left intact.

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::destructChildren ( )
 

Disposes of all objects whose owner is this object. This method is called internally when destroying a simple module with all objects it holds.

The actual method of "disposing of" an object depends on the storage class of the object:

  • dynamic (allocated on the heap): operator delete
  • auto (allocated on the stack, i.e. it is a local variable of activity()): direct destructor call
  • static (global variable): setOwner(NULL) which makes the object join its default owner
See also:
storage()

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, 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, cNetworkType, cFunctionType, cClassRegister, cInspectorFactory, 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, cGate, cHead, cMessage, cModule, cSimpleModule, cMessageHeap, 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, cEnum, cFSM, cGate, cLinkedList, cMessage, cSimpleModule, cCompoundModule, cMessageHeap, cOutVector, cPacket, cPar, cQueue, cStdDev, cTopology, and cWatch.

TInspector * cObject::inspector ( int type,
void * data ) [virtual]
 

Create an inspector window. Used internally. As of Jan 1999, this function should not be used directly any more; see inspectorFactoryName() and Register_InspectorFactory() instead.

const char * cObject::inspectorFactoryName ( ) const [inline, virtual]
 

Returns the name of the inspector factory class associated with this class. Inspector factories are used by graphical user interfaces like Tkenv. They are capable of creating inspector windows for objects of this class (and maybe also other classes).

Reimplemented in cBag, cArray, cDensityEstBase, cFSM, cGate, cHead, cLinkedList, cMessage, cModule, cSimpleModule, cCompoundModule, cMessageHeap, cNetMod, cOutVector, cPacket, cPar, cModulePar, cQueue, cSimulation, cStatistic, cTopology, and cWatch.

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

Returns true if the object's name is identical with 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, 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, 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. Most derived classes contain a cClassName& cClassName::operator=(cClassName &) function. Copies the object EXCEPT for the NAME string; derived classes are expected to define similar functions (e.g. cPar::operator=(cPar &)) If you want to copy the name string, you can do it by hand: setName(o.name()).

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. If NULL is passed, the default owner of the object will be used.

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 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:
Generated at Sat May 4 15:45:50 2002 for OMNeT++ by doxygen1.2.8.1 written by Dimitri van Heesch, © 1997-2001