cObject Class Reference

#include <cobject.h>

Description

cObject is a lightweight class which serves as the root of the OMNeT++ class hierarchy. cObject, via virtual and pure virtual methods, defines several properties and mechanisms that are used throughout the entire simulation library.

These mechanisms are the following:

• Name string. There are three virtual methods: getName(), getFullName() and getFullPath(). They are expected to be overridden subclasses as cObject only contains trivial implementations, e.g. getName() always returns the empty string. getName() returns a "base name"; getFullName() augments the base name with auxiliary information such as an index; and getFullPath() includes the object's location in the object hierarchy. An example: for a module in a network simulation, getName() may return "eth", getFullName() may return "eth[2]", and getFullPath() may return "Net.host[4].eth[2]".
• Class name. getClassName() returns the fully qualified C++ class name. Its operation is based on the C++ typeid() operator and the type_info class.
• Info string. The str() method can be overridden in subclasses to return a one-line concise description of the object's contents, e.g. for display in graphical user interfaces.
• Cloning. The dup() method is to be overridden in subclasses to return an exact copy of this object.
• Iteration. The forEachChild() method is to be overridden in subclasses to iterate over (cObject-derived) objects that it contains or holds. This method is primarily used by graphical user interfaces to display an object hierarchy, and for searching.
• Ownership mechanism. The ownership mechanism helps define an object containment hierarchy, and also defines responsibility of deletion. Several methods belong here, the most visible one being getOwner(). A cObject itself does not keep track of its owner (the method returns nullptr), an actual owner pointer is added by the subclass cOwnedObject. cObject also provides the drop(), take() and dropAndDelete() methods that sublasses may utilize in implementing their ownership management.
• Packing/unpacking. The parsimPack() and parsimUnpack() methods can be overridden to allow instances to be transferred via MPI for parallel simulation.
• Reflection. The getDescriptor() method returns a cClassDescriptor object that allows for enumerating the object's fields, getting/setting their values, etc.

In model code, it usually makes sense to use cObject as a base class for any class that is expected to be polymorphic. In this case, cObject does not add any runtime overhead (as it contains no data members). The appropriate member functions (dup(), str(), etc.) are expected to be redefined.

Inheritance diagram for cObject:

Public Member Functions
	cObject ()
	cObject (const cObject &other)=default
virtual	~cObject ()
virtual const char *	getClassName () const
Empty virtual functions which can be redefined in subclasses
virtual const char *	getName () 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
Support for parallel execution.
These functions pack/unpack the object from/to a communication buffer, and should be redefined in classes whose instances are expected to travel across partitions.
virtual void	parsimPack (cCommBuffer *buffer) const
virtual void	parsimUnpack (cCommBuffer *buffer)
Miscellaneous functions.
virtual cObject *	getOwner () const
virtual bool	isOwnedObject () const
virtual bool	isSoftOwner () const
virtual void	forEachChild (cVisitor *v)
cObject *	findObject (const char *name, bool deep=true)
virtual cClassDescriptor *	getDescriptor () const
Helper functions.
void	copyNotSupported () const

Protected Member Functions
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.
virtual void	take (cOwnedObject *obj)
virtual void	drop (cOwnedObject *obj)
void	dropAndDelete (cOwnedObject *obj)

Constructor & Destructor Documentation

cObject() [1/2]

cObject ( )

inline

Constructor. It has an empty body. (The class does not have data members and there is nothing special to do at construction time.)

cObject() [2/2]

cObject ( const cObject &  other )

default

Copy constructor. It has an empty body. (The class does not have data members and there is nothing special to do at construction time.) Subclasses should call the copy constructor of their base classes from their own copy constructors.

~cObject()

virtual ~cObject ( )

virtual

Destructor. It has an empty body (the class does not have data members.) It is declared here only to make the class polymorphic and make its destructor virtual.

Member Function Documentation

getClassName()

virtual const char* getClassName ( ) const

virtual

Returns the (fully qualified) class name. This method is implemented using typeid (C++ RTTI), and it does not need to be overridden in subclasses.

Reimplemented in cWatch_cObjectPtr, cWatch_cObject, cWatch_stdstring, cWatch_uchar, cWatch_char, cWatch_bool, cGenericAssignableWatch< T >, and cGenericReadonlyWatch< T >.

Referenced by cWatch_cObject::str(), and cWatch_cObjectPtr::str().

getName()

virtual const char* getName ( ) const

inlinevirtual

Returns pointer to the object's name. It should never return nullptr. This default implementation just returns an empty string ("").

Reimplemented in cXMLElement, cGate, cPar, cNamedObject, cResultRecorder, and cProperties.

isName()

bool isName

(

const char *

s

)

const

Returns true if the object's name is identical to the string passed.

getFullName()

virtual const char* getFullName ( ) const

inlinevirtual

When this object is part of a vector (like a submodule can be part of a module vector, or a gate can be part of a gate vector), this method returns the object's name with the index in brackets; for example: "out[5]".

This default implementation just returns getName().

Reimplemented in cModule, cComponentType, cGate, and cProperty.

Referenced by cWatch_cObject::str(), and cWatch_cObjectPtr::str().

getFullPath()

virtual std::string getFullPath ( ) const

virtual

Returns the full path of the object in the object hierarchy, like "net.host[2].tcp.winsize". This method relies on getOwner(): if there is an owner object, this method returns the owner's fullPath plus this object's fullName, separated by a dot; otherwise it simply returns fullName.

Reimplemented in cModule, cSimulation, and cResultRecorder.

getClassAndFullName()

virtual std::string getClassAndFullName ( ) const

virtual

Returns a string that contains the class name and the full name of the object in a human-friendly format. Example: "(cMessage)msg"

See also

getClassName(), getFullName()

getClassAndFullPath()

virtual std::string getClassAndFullPath ( ) const

virtual

Returns a string that contains the class name and the full path of the object in a human-friendly format. Example: "(cMessage)foo.bar.msg"

See also

getClassName(), getFullPath()

getThisPtr()

const cObject* getThisPtr ( ) const

inline

Returns the this pointer. Utility function for the logging macros.

str()

virtual std::string str ( ) const

virtual

Returns a brief, one-line description of the object. The returned string does (should) NOT include the object's name and class. This method is used to display object information at several places in the Qtenv GUI, among others.

Reimplemented in cCanvas, cPixmapFigure, cImageFigure, cAbstractTextFigure, cPathFigure, cPolygonFigure, cPieSliceFigure, cRingFigure, cOvalFigure, cRectangleFigure, cAbstractShapeFigure, cPolylineFigure, cArcFigure, cLineFigure, cAbstractLineFigure, cPanelFigure, cGroupFigure, cPoisson, cNegBinomial, cGeometric, cBinomial, cBernoulli, cIntUniformExcl, cIntUniform, cParetoShifted, cWeibull, cTriang, cModule, cCauchy, cFigure, cStudentT, SumPerDurationFilter, cTopology, cChiSquare, RemoveRepeatsFilter, TimeAverageFilter, cErlang, AverageFilter, MaxFilter, cOwnedDynamicExpression, MinFilter, cBeta, cSimpleModule, MeanFilter, SumFilter, cGamma, StatisticsRecorder, CountNanFilter, cWatch_cObjectPtr, cRealTimeScheduler, cFSM, TimeAverageRecorder, cMultiFingerprintCalculator, cWatch_cObject, cMessage, cTruncNormal, cObjectParImpl, cQueue, AverageRecorder, cWatch_stdstring, cBoolParImpl, cDoubleParImpl, cStringParImpl, cIntParImpl, MaxRecorder, cXMLParImpl, cGate, cXMLElement, cSingleFingerprintCalculator, cMsgPar, cDatarateChannel, cArray, cWatch_uchar, MinRecorder, cSequentialScheduler, cNormal, cOsgCanvas, MeanRecorder, cPacket, cChannel, cWatch_char, cPar, ConstantFilter, cProperty, cNedMathFunction, cExponential, SumRecorder, cWatch_bool, cNedFunction, cEvent, cEventHeap, cSoftOwner, TotalCountFilter, cValueHolder, cValueMap, cEnum, LastValueRecorder, cValueArray, cGenericAssignableWatch< T >, cOutVector, cPacketQueue, cProperties, cConfigOption, cUniform, cStdDev, DemuxFilter, cScheduler, cGenericReadonlyWatch< T >, TotalCountRecorder, cFutureEventSet, cObjectFactory, cRegistrationList, WarmupPeriodFilter, and VectorRecorder.

Referenced by cWatch_cObject::str(), and cWatch_cObjectPtr::str().

printOn()

virtual std::ostream& printOn ( std::ostream &  os ) const

virtual

Prints the object on the given stream. The default implementation prints the class name, the object full name, and the brief description. The default stream output operator (operator<<) for cObject descendants delegates to this method.

See also

getClassName(), getFullName, str()

dup()

virtual cObject* dup ( ) const

virtual

Should be redefined in subclasses to create an exact copy of this object. The default implementation just throws an error, to indicate that the method was not redefined.

Reimplemented in cEvent, cCanvas, cPixmapFigure, cIconFigure, cImageFigure, cAbstractImageFigure, cLabelFigure, cTextFigure, cAbstractTextFigure, cPathFigure, cPolygonFigure, cPieSliceFigure, cRingFigure, cOvalFigure, cRectangleFigure, cAbstractShapeFigure, cPolylineFigure, cArcFigure, cLineFigure, cAbstractLineFigure, cPanelFigure, cGroupFigure, cPoisson, cNegBinomial, cGeometric, cBinomial, cBernoulli, cIntUniformExcl, cIntUniform, cParetoShifted, cWeibull, cTriang, cCauchy, cFigure, cStudentT, cTopology, cChiSquare, cAutoRangeHistogramStrategy, cErlang, cOwnedDynamicExpression, cBeta, cNoncopyableOwnedObject, cDefaultHistogramStrategy, cGamma, cFSM, cKSplit, cMultiFingerprintCalculator, cMessage, cTruncNormal, cQueue, cSingleFingerprintCalculator, cMsgPar, cArray, cNormal, cHistogram, cOsgCanvas, cPacket, cProperty, cExponential, cFixedRangeHistogramStrategy, cParImpl, cEventHeap, cValueHolder, cValueMap, cEnum, cValueArray, cObjectParImpl, cPacketQueue, cUniform, cProperties, cPSquare, cAbstractHistogram, cStdDev, cBoolParImpl, cDoubleParImpl, cStringParImpl, cIntParImpl, and cXMLParImpl.

Referenced by cMultiFingerprintCalculator::dup().

take()

virtual void take ( cOwnedObject *  obj )

protectedvirtual

Makes this object the owner of obj. This method should be called by container classes when they take ownership of an object inserted into them.

The obj pointer should not be nullptr.

Reimplemented in cSoftOwner.

drop()

virtual void drop ( cOwnedObject *  obj )

protectedvirtual

Releases ownership of obj, giving it back to its default owner. This method should be called by container classes when an object is removed from the container.

The obj pointer should not be nullptr.

Reimplemented in cSoftOwner.

dropAndDelete()

void dropAndDelete ( cOwnedObject *  obj )

protected

This is a shortcut for the sequence

  drop(obj);
  delete obj;

It is especially useful when writing destructors and assignment operators.

Passing nullptr is allowed.

See also

drop()

parsimPack()

virtual void parsimPack ( cCommBuffer *  buffer ) const

virtual

Serializes the object into a buffer. This default implementation throws an exception ("packing not implemented").

Reimplemented in cKSplit, cMessage, cQueue, cMsgPar, cArray, cOwnedObject, cHistogram, cPacket, cProperty, cPrecollectionBasedDensityEst, cEvent, cParImpl, cPacketQueue, cProperties, cStdDev, cNamedObject, cPSquare, and cStatistic.

parsimUnpack()

virtual void parsimUnpack ( cCommBuffer *  buffer )

virtual

Deserializes the object from a buffer. This default implementation just throws an exception ("packing not implemented").

Reimplemented in cKSplit, cMessage, cQueue, cMsgPar, cArray, cOwnedObject, cHistogram, cPacket, cProperty, cPrecollectionBasedDensityEst, cEvent, cParImpl, cPacketQueue, cProperties, cStdDev, cNamedObject, cPSquare, and cStatistic.

getOwner()

virtual cObject* getOwner ( ) const

inlinevirtual

Returns the owner (or parent) object. nullptr as return value is legal, and may mean "unknown" (=not tracked) or "no owner". This default implementation just returns nullptr (meaning "unknown"). (With the cOwnedObject subclass which does maintain an owner pointer, a nullptr return value would mean "no owner".)

Reimplemented in cOwnedObject, cGate, cXMLElement, and cPar.

isOwnedObject()

virtual bool isOwnedObject ( ) const

inlinevirtual

Returns true if this class is a subclass of cOwnedObject. This is a performance optimization, to avoid frequent calls to dynamic_cast<>. In cObject this method returns false, in cOwnedObject it returns true, and it MUST NOT be defined on any other class.

Reimplemented in cOwnedObject.

isSoftOwner()

virtual bool isSoftOwner ( ) const

inlinevirtual

Returns true if this object is a "soft owner" and false otherwise. Currently the only soft owner class is cSoftOwner (and its subclasses, most notably cModule and cSimpleModule), all others are "hard owners". An object is soft owner if it allows another object to take ownership (via take()) of an object it currently owns. Hard owners will raise an error if some other object tries to take() an object that they own.

Reimplemented in cSoftOwner.

forEachChild()

virtual void forEachChild ( cVisitor *  v )

virtual

Enables traversing the object tree, performing some operation on each object. The operation is encapsulated in the particular subclass of cVisitor.

This method should be redefined in every subclass to call v->visit(obj) for every obj object contained.

Reimplemented in cWatch_cObjectPtr, cWatch_cObject, cCanvas, cModule, cFigure, cComponent, cSimpleModule, StatisticsRecorder, cMessage, cQueue, cXMLElement, cMsgPar, cArray, cGate, cPacket, cPar, cSimulation, cEvent, cEventHeap, cSoftOwner, cValueHolder, cValueMap, cValueArray, cResultFilter, and cRegistrationList.

findObject()

cObject* findObject	(	const char *	name,
		bool	deep = true
	)

Finds the object with the given name. This function is useful when called on subclasses that are containers. This method finds the object with the given name in a container object and returns a pointer to it or nullptr if the object has not 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 forEachChild() mechanism.

Do not use it for finding submodules! Use cModule::getModuleByRelativePath() instead.

getDescriptor()

virtual cClassDescriptor* getDescriptor ( ) const

virtual

Returns the descriptor object for (the class of) this object.

Reimplemented in cWatch_cObjectPtr, and cWatch_cObject.

copyNotSupported()

void copyNotSupported

(

)

const

Convenience function: throws a cRuntimeError ("copying not supported") stating that assignment, copy constructor and dup() will not work for this object. You can call this from operator=() if you do not want to implement object copying.

---

The documentation for this class was generated from the following file:

• cobject.h