OMNeT++ Simulation Library  5.6.1
cOwnedObject Class Reference

#include <cownedobject.h>


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.
Inheritance diagram for cOwnedObject:
cNamedObject cObject cArray cCanvas cEnum cEvent cFigure cFSM cFutureEventSet cMsgPar cNoncopyableOwnedObject cOsgCanvas cQueue cRandom cTopology

Public Member Functions

Constructors, destructor, assignment.
 cOwnedObject ()
 cOwnedObject (const char *name, bool namepooling=true)
 cOwnedObject (const cOwnedObject &obj)
virtual ~cOwnedObject ()
cOwnedObjectoperator= (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 ()
cNamedObjectoperator= (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)
virtual ~cObject ()
virtual const char * getClassName () const
bool isName (const char *s) const
virtual const char * getFullName () const
virtual std::string getFullPath () const
const cObjectgetThisPtr () const
virtual std::string str () const
virtual _OPPDEPRECATED std::string info () const
virtual _OPPDEPRECATED std::string detailedInfo () const
virtual cObjectdup () const
virtual void forEachChild (cVisitor *v)
cObjectfindObject (const char *name, bool deep=true)
void copyNotSupported () const

Static Public Member Functions

static long getTotalObjectCount ()
static long getLiveObjectCount ()
static void resetObjectCounters ()

Object ownership

virtual cObjectgetOwner () const override
virtual bool isOwnedObject () const override
virtual bool isSoftOwner () const
static cDefaultListgetDefaultOwner ()

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]

Create object without a name. The object will be initially owned by defaultOwer().

◆ cOwnedObject() [2/3]

cOwnedObject ( const char *  name,
bool  namepooling = true 

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 ~cOwnedObject ( )


Member Function Documentation

◆ operator=()

cOwnedObject& operator= ( const cOwnedObject 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.getName()).

Ownership of the object is not affected by assigments.

◆ parsimPack()

virtual void parsimPack ( cCommBuffer buffer) const

◆ parsimUnpack()

virtual void parsimUnpack ( cCommBuffer buffer)

◆ getOwner()

virtual cObject* getOwner ( ) const

Returns pointer to the owner of the object.

Reimplemented from cObject.

◆ isOwnedObject()

virtual bool isOwnedObject ( ) const

Returns true.

Reimplemented from cObject.

◆ isSoftOwner()

virtual bool isSoftOwner ( ) const

Returns false in cOwnedObject and in all derived classes except cDefaultList. An object A is a "soft owner" if it allows a B object take() an object A owns. "Hard owners" will raise an error if some other object tries to take() an object they own. The only soft owner class is cDefaultList.

Reimplemented in cDefaultList.

◆ getDefaultOwner()

static cDefaultList* getDefaultOwner ( )

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.

◆ getTotalObjectCount()

static long getTotalObjectCount ( )

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

static long getLiveObjectCount ( )

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

static void resetObjectCounters ( )

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: