cOwnedObject Class Reference
[Simulation core classes]
Base class for several classes in the OMNeT++ library. More...
#include <cownedobject.h>
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) |
| virtual void | parsimUnpack (cCommBuffer *buffer) |
Static Public Member Functions | |
Statistics. | |
| static long | getTotalObjectCount () |
| static long | getLiveObjectCount () |
| static void | resetObjectCounters () |
Friends | |
| class | cObject |
| class | cDefaultList |
| class | cSimulation |
| class | cMessage |
| class | cPacket |
Object ownership | |
|
| |
| virtual cObject * | getOwner () const |
| virtual bool | isOwnedObject () const |
| virtual bool | isSoftOwner () const |
| static cDefaultList * | getDefaultOwner () |
Detailed Description
Base class for several 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.
When subclassing cOwnedObject, some virtual member functions are expected to be redefined: dup() are mandatory to be redefined, and often you'll want to redefine info() and detailedInfo() as well.
Ownership management helps OMNeT++ catch common programming errors. As a definition, 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.
Constructor & Destructor Documentation
| cOwnedObject::cOwnedObject | ( | ) |
Create object without a name.
The object will be initially owned by defaultOwer().
| cOwnedObject::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.
Member Function Documentation
| static cDefaultList* cOwnedObject::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.
| static long cOwnedObject::getLiveObjectCount | ( | ) | [inline, static] |
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.
| static long cOwnedObject::getTotalObjectCount | ( | ) | [inline, static] |
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.
| virtual bool cOwnedObject::isSoftOwner | ( | ) | const [inline, virtual] |
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.
| cOwnedObject& 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.
| static void cOwnedObject::resetObjectCounters | ( | ) | [inline, static] |
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:
