#include <cobject.h>
Inheritance diagram for cObject::
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 |
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:
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.
|
Copy constructor. In derived classes, it is usually implemented as |
|
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 If there is no active simple module (we're not in a simulation), the owner will be NULL. |
|
Create object with given name. See cObject() constructor about initial ownership of the object. |
|
Destructor. It does the following:
|
|
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. |
|
This function compares to objects by name. It can be used in a priority queue (class cQueue) as a sorting criterion. |
|
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. |
|
Returns pointer to the default owner of the object. This function is used by the drop() member function. |
|
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. |
|
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); |
|
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() ); |
|
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 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. |
|
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. |
|
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. |
|
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(). |
|
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. |
|
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. |
|
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. |
|
Returns true if the object's name is identical to the string passed. |
|
Returns pointer to the object's name. The function never returns NULL; rather, it returns ptr to "". |
|
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. |
|
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. |
|
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).
|
|
The assignment operator. Derived classes should contain similar methods (
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: Ownership of the object is not affected by assigments. |
|
Returns pointer to the owner of the object. |
|
Sets object's name. The object creates its own copy of the string. NULL pointer may also be passed. Reimplemented in cOutVector. |
|
Sets the owner of the object. NULL is legal a legal value and means that no object will own this one (ownerp=NULL).
|
|
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().) |
|
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 ); |
|
Returns the flag which determines whether the container object should automatically take ownership of the objects that are inserted into it. |
|
Sets the flag which determines whether the container object should automatically take ownership of the objects that are inserted into it. |
|
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. |
|
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. |