cOwnedObject Class Reference

#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.

Inheritance diagram for cOwnedObject:

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)
virtual	~cObject ()
virtual const char *	getClassName () const
bool	isName (const char *s) const
virtual const char *	getFullName () const
virtual std::string	getFullPath () const
const cObject *	getThisPtr () const
virtual std::string	str () const
virtual _OPPDEPRECATED std::string	info () const
virtual _OPPDEPRECATED std::string	detailedInfo () const
virtual cObject *	dup () const
virtual void	forEachChild (cVisitor *v)
cObject *	findObject (const char *name, bool deep=true)
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
virtual bool	isSoftOwner () const
static cDefaultList *	getDefaultOwner ()

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]

cOwnedObject ( const char *  name, bool  namepooling = true  )

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 ~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&)).

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

overridevirtual

Serializes the object into a buffer.

Reimplemented from cNamedObject.

Reimplemented in cTopology, cNoncopyableOwnedObject, cLegacyHistogram, cFSM, cKSplit, cMessage, cQueue, cArray, cMsgPar, cHistogram, cPacket, cChannel, cPrecollectionBasedDensityEst, cEvent, cDefaultList, cVarHistogram, cOutVector, cPacketQueue, cStdDev, cPSquare, cLegacyHistogramBase, and cStatistic.

parsimUnpack()

virtual void parsimUnpack ( cCommBuffer *  buffer )

overridevirtual

Deserializes the object from a buffer.

Reimplemented from cNamedObject.

Reimplemented in cTopology, cNoncopyableOwnedObject, cLegacyHistogram, cFSM, cKSplit, cMessage, cQueue, cArray, cMsgPar, cHistogram, cPacket, cChannel, cPrecollectionBasedDensityEst, cEvent, cDefaultList, cVarHistogram, cPacketQueue, cOutVector, cStdDev, cPSquare, cLegacyHistogramBase, and cStatistic.

getOwner()

virtual cObject* getOwner ( ) const

inlineoverridevirtual

Returns pointer to the owner of the object.

Reimplemented from cObject.

isOwnedObject()

virtual bool isOwnedObject ( ) const

inlineoverridevirtual

Returns true.

Reimplemented from cObject.

isSoftOwner()

virtual bool isSoftOwner ( ) const

inlinevirtual

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

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.

getTotalObjectCount()

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

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

static void 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:

• cownedobject.h