Initializing Data Structures

There is a handler class to manage many tasks related to data structures, appropriately named DsHandler.

The DsHandler class holds a list with all defined data structures that are loaded at one given time. To properly use these data structures, DsHandler class provides static methods to access the class objects or to create value objects.

You can call these methods directly on the class, no object instance is needed.

Methods for handling data structure class objects

const TypeClass& DsHandler::findClass        (const String& pName);
const TypeClass* DsHandler::findClassPointer (const String& pName);
bool             DsHandler::isDataStructure  (const String& pName);

findClass searches and returns a const reference to a data structure by its name. When the data structure is not found it throws a NotFoundDataTypeException. The second method, findClassPointer, returns a const pointer to a specified data structure and NULL when it is not found. With isDataStructure you can test if a given data structure exists (is loaded) or not. Do not try to change the references returned by this methods.

Deprecated method for handling data structure class objects

There is an old method still available,

const Type* DsHandler::findStructure (const char* pName);

but take care if you use the findStructure method. It is only there for compatibility and now generates a memory leak. It is therefore recommended to replace this method with the findClass method.

Methods to create data structure values

Type& DsHandler::newValue           (const Kernel::String& pName);
Type& DsHandler::newInteger         ();
Type& DsHandler::newFloat           ();
Type& DsHandler::newIntVector       (unsigned int pLength, int pDefault=0);
Type& DsHandler::newFloatVector     (unsigned int pLength, double pDefault=0);
Type& DsHandler::newValueFromString (const Kernel::String& pStr);

All these methods throw a NotFoundDataTypeException when the specified data structure is not found. In primitives design use TypeRef class in case you have a non const Type object and ConstTypeRef when you have a const Type object. The life time of this object determines the creation and releasing of a data structure value.

Example:

go
{
  TypeRef tData = DsHandler::newValue("Root.Protocol.TCPProtocol");
  // do something with it
}
// at the exit of the method the object is deleted and the TypeRef destructor is called.
// This frees the data structure value.

You may use the TypeRef class constructor directly to instantiate a data structure (without using DsHandler), but only the TypeRef class constructor.

TypeRef tData("Root.Protocol.TCPProtocol");
// creates an objects that holds a reference
// to a TCPProtocol data structureTypeRef tData("Root.Protocol.TCPProtocol");

Deprecated methods to create data structure values

There are old methods still available for compatibility:

Type* DsHandler::makeNewStructure  (const char* pName);
Type* DsHandler::makeNewInt        ();
Type* DsHandler::makeNewFloat      ();
Type* DsHandler::makeNewFromString (const char* pString) throw (DataTypeException);

Data Structure Values

During the simulation a certain number of data structure values is generated. There is a mechanism that saves you from the overhead of creating, duplicating or releasing data structure values. MLDesigner uses a pool mechanism to reuse created values that are no longer needed.

Every data structure has a reference counter that is increased when an object refers to it, and decreased every time an object stops refering to the data structure. When the reference counter reaches zero the value is free and put into a pool of free values. A clone method looks first if there are any free data structures in the pool to be reused, if not a new data structure is created.

Use a reference class (TypeRef or derived) every time you want to work with data structures. Every time a method returns Type& or Type* you can assign it to a TypeRef or a derived class. When it returns a const reference, you have to use the ConstTypeRef class. As a general rule you have to know that non const references returned by methods are in fact copies of the original data structure inside and every time a method returns a const reference, this is a reference to the real object inside.