#include <cownedobject.h>
Description
A cObject that keeps track of its owner. It serves as base class for many classes in the OMNeT++ library.
Instances of cOwnedObjects are kept track of by the simulation kernel, and may be inserted into cQueue and cArray.
It is not always a good idea to subclass your own classes from cOwnedObject, especially if they are small data objects. The more lightweight cObject is often a better choice.
Ownership management helps OMNeT++ catch common programming errors. The term ownership means the exclusive right and duty to delete owned objects.
cOwnedObjects hold a pointer to their owner objects; the getOwner() 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 is 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 is 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 is in the queue, you'll get an error message instead of just a crash. This is because cOwnedObject 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 cOwnedObject-subclass object gets inserted into any cOwnedObject-subclass container (cQueue, cArray).
Some more details, in case you are 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 cOwnedObject-subclasses as data members: your class (the enclosing object) should own them – call take() from the constructor and drop() from the destructor.
Public Member Functions | |
Constructors, destructor, assignment. | |
| cOwnedObject () | |
| cOwnedObject (const char *name, bool namepooling=true) | |
| cOwnedObject (const cOwnedObject &obj) | |
| virtual | ~cOwnedObject () |
| cOwnedObject & | operator= (const cOwnedObject &o) |
| virtual void | parsimPack (cCommBuffer *buffer) const override |
| virtual void | parsimUnpack (cCommBuffer *buffer) override |
 Public Member Functions inherited from cNamedObject | |
| cNamedObject () | |
| cNamedObject (const char *name, bool namepooling=true) | |
| cNamedObject (const cNamedObject &obj) | |
| virtual | ~cNamedObject () |
| cNamedObject & | operator= (const cNamedObject &o) |
| virtual void | setName (const char *s) |
| virtual const char * | getName () const override |
| virtual void | setNamePooling (bool b) |
| virtual bool | getNamePooling () |
| Public Member Functions inherited from cObject | |
| cObject () | |
| cObject (const cObject &other)=default | |
| virtual | ~cObject () |
| virtual const char * | getClassName () const |
| bool | isName (const char *s) const |
| virtual const char * | getFullName () const |
| virtual std::string | getFullPath () const |
| virtual std::string | getClassAndFullName () const |
| virtual std::string | getClassAndFullPath () const |
| const cObject * | getThisPtr () const |
| virtual std::string | str () const |
| virtual std::ostream & | printOn (std::ostream &os) const |
| virtual cObject * | dup () const |
| virtual bool | isSoftOwner () const |
| virtual void | forEachChild (cVisitor *v) |
| cObject * | findObject (const char *name, bool deep=true) |
| virtual cClassDescriptor * | getDescriptor () const |
| void | copyNotSupported () const |
Static Public Member Functions | |
Statistics. | |
| static long | getTotalObjectCount () |
| static long | getLiveObjectCount () |
| static void | resetObjectCounters () |
Object ownership | |
| virtual cObject * | getOwner () const override |
| virtual bool | isOwnedObject () const override |
| static cSoftOwner * | getOwningContext () |
Additional Inherited Members | |
| Protected Member Functions inherited from cObject | |
| virtual void | take (cOwnedObject *obj) |
| virtual void | drop (cOwnedObject *obj) |
| void | dropAndDelete (cOwnedObject *obj) |
Constructor & Destructor Documentation
◆ cOwnedObject() [1/3]
| cOwnedObject | ( | ) |
Create object without a name. The object will be initially owned by defaultOwer().
◆ cOwnedObject() [2/3]
|
explicit |
Create object with given name. The object will be initially owned by defaultOwer(). Name pooling is an optimization feature.
◆ cOwnedObject() [3/3]
| cOwnedObject | ( | const cOwnedObject & | obj | ) |
Copy constructor.
◆ ~cOwnedObject()
|
virtual |
Destructor.
Member Function Documentation
◆ operator=()
| cOwnedObject& operator= | ( | const cOwnedObject & | o | ) |
The assignment operator. Derived classes should contain similar methods (cClassName& cClassName::operator=(cClassName&)).
Assignment 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.getName()).
Ownership of the object is not affected by assignments.
◆ parsimPack()
|
overridevirtual |
Serializes the object into a buffer.
Reimplemented from cNamedObject.
Reimplemented in cKSplit, cMessage, cQueue, cMsgPar, cArray, cHistogram, cPacket, cPrecollectionBasedDensityEst, cEvent, cPacketQueue, cStdDev, cPSquare, and cStatistic.
◆ parsimUnpack()
|
overridevirtual |
Deserializes the object from a buffer.
Reimplemented from cNamedObject.
Reimplemented in cKSplit, cMessage, cQueue, cMsgPar, cArray, cHistogram, cPacket, cPrecollectionBasedDensityEst, cEvent, cPacketQueue, cStdDev, cPSquare, and cStatistic.
◆ getOwner()
|
inlineoverridevirtual |
Returns pointer to the owner of the object.
Reimplemented from cObject.
◆ isOwnedObject()
|
inlineoverridevirtual |
Returns true.
Reimplemented from cObject.
◆ getOwningContext()
|
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 component in context (see cSimulation::getContext()).
◆ getTotalObjectCount()
|
inlinestatic |
Returns the total number of objects created since the start of the program (or since the last reset). The counter is incremented by cOwnedObject 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.
◆ getLiveObjectCount()
|
inlinestatic |
Returns the number of objects that currently exist in the program. The counter is incremented by cOwnedObject constructor and decremented by the destructor. May be useful for profiling or debugging memory leaks.
◆ resetObjectCounters()
|
inlinestatic |
Reset counters used by getTotalObjectCount() and getLiveObjectCount(). (Note that getLiveObjectCount() may go negative after a reset call.)
The documentation for this class was generated from the following file:
