5. Working with Smart Pointers
<< RETURN TO THE PREVIOUS SECTION
In UNIGINE, instances of C++ API classes (such as: node, mesh, body, image, etc.) only store pointers to instances of internal C++ classes, they cannot be created and deleted via the standard new/delete operators. So they should be declared as smart pointers (Unigine::Ptr) that allow you to automatically manage their lifetime. UNIGINE has its own optimized memory allocator for faster and more efficient memory management. Each smart pointer stores a reference counter, i.e. how many smart pointers are pointing to the managed object; when the last smart pointer is destroyed, the counter goes to 0, and the managed object is then automatically deleted.
To create an instance of a class we should declare a smart pointer for the class we are going to instantiate and call the create() method - class constructor - providing construction parameters if necessary.
Ownership of each instance matters on its deletion and can be managed using grab() and release() methods.
// instantiating an object of an internal class named object
<Class>Ptr instance = <Class>::create(<construction_parameters>);
// release ownership
instance->release();
// grab ownership
instance->grab();
// clears the smart pointer
instance.clear();
// destroys the smart pointer
instance.destroy();The following example illustrates instancing for the NodeDummy class and difference between clearing and destroying smart pointers:
//--------------------------------------------------------------------
// Case 1: clearing a smart pointer
//--------------------------------------------------------------------
// creating a NodeDummy (now reference counter = 1)
NodeDummyPtr ND1 = NodeDummy::create();
// setting the second pointer to point to the created NodeDummy (now reference counter = 2)
NodeDummyPtr ND2 = ND1;
// clearing ND1 pointer (now reference counter = 1)
ND1.clear();
// ND2 still has the object and we can manage it
ND2->setEnabled(1);
// clearing ND2 pointer (now reference counter = 0 and the object will be deleted automatically)
ND2.clear();
//--------------------------------------------------------------------
// Case 2: destroying a smart pointer
//--------------------------------------------------------------------
// creating a NodeDummy (now reference counter = 1)
NodeDummyPtr ND1 = NodeDummy::create();
// setting the second pointer to point to the created NodeDummy (now reference counter = 2)
NodeDummyPtr ND2 = ND1;
// destroying ND1 pointer (the object is deleted automatically)
ND1.destroy();
// ND2 is no longer accessible, so this line will lead to an error
ND2->setEnabled(1);When creating a smart pointer you should remember about its scope, e.g. when you create a smart pointer inside a function, its scope is limited by this function.
Additional information:
- For more information on ownership management, see Memory Management page.
- For more information on managing smart pointers, see Ptr class page.