# Visualization Library A lightweight C++ OpenGL middleware for 2D/3D graphics | [Home] [Tutorials] [All Classes] [Grouped Classes]

# Smart Pointers and Memory Management Tutorial

Smart Pointers

Visualization applications often deal with a large amount of objects and complex data structures. This complexity makes it very difficult to track the reference relationship between objects. This is a typical problem in C++ since it does not provide any out-of-the-box garbage collection or automatic memory management system. Among the most common problems that a C++ application has to deal with we find:

- invalid pointers (deallocating objects that are still being used), result: crash.
- multiple memory release (objects released more than once), result: crash.
- memory leaks (objects never deallocated), result: unrecoverable memory consumption.

In order to minimize this issues Visualiation Library employs a well-known, simple and effective techniqe called "reference counting". For every dynamically allocated object VL keeps a reference count that tracks the number of references that an object has. When the reference reaches zero it means that no one is using that object anymore and that it can be safely deleted. All the reference counted classes derive from vl::Object, while the actual reference count is managed by the template class vl::ref<>. The vl::ref<> class behaves similarly to Boost's smart pointer "boost::intrusive_ptr<>".

Basic usage

The following example shows the basic usage of the `ref<>` class:

    class MyObject: public vl::Object
    {
    public:
        MyObject(int data): mData(data) {}
        int mData;
    };

    int main()
    {
        // the ref<> class can be used for the most part like a normal pointer
        vl::ref<MyObject> obj1 = new MyObject(10);
        MyObject obj3(30);
        *obj1 = obj3; // supports the '*' operator
        obj1->mData = 40; // supports the '->' operator
        MyObject* naked = obj1.get(); // retrieves the naked pointer
        if (obj1) // bool operator -> obj1.get() != NULL
            doSomething();
        vl::ref<MyObject> obj2 = new MyObject(20);
        if (obj1 == obj2) // == and != operators
            doSomethingElse();
        std::map< vl::ref<MyObject>, int > mMyMap; // can be used with STD maps and sets
    }

Now consider the following example:

    void myfunc()
    {
      vl::ref<MyObject> obj_ref = new MyObject; // ref count is 1
      obj_ref->someMethod();
    }
    // "obj_ref" goes out of scope and frees the allocated memory

The function `myfunc()` allocates an object of type `MyObject` deriving from (vl::Object), then calls the method `someMethod()` and then returns. As you can see there is no need to explicitly call the `delete` operator to deallocate the object pointed by `obj_ref`. Infact when `obj_ref` goes out of scope its destructor will decrement the reference count of the previously allocated object (which will reach 0) and will deallocate it.

The power of this kind of memory management system though is much more evident when applied to complex or hierarchycal data structures. Consider the following example:

    class TreeNode: public vl::Object
    {
    public:
      TreeNode(const std::string& name): mName(name) {}

      void addChild(TreeNode* child) { mChildNodes.push_back(child); }
      void removeChild(int i) { mChildNodes.erase(mChildNodes.begin()+i); }

    public:
      std::vector< vl::ref<TreeNode> > mChildNodes;
      std::string mName;
    };

    void mytree()
    {
      vl::ref<TreeNode> nodeA = new TreeNode("A"); // A's ref count == 1
      TreeNode* nodeB = new TreeNode("B"); // B's ref count == 0
      TreeNode* nodeC = new TreeNode("C"); // C's ref count == 0
      nodeA->addChild(nodeB); // B's ref count == 1
      nodeA->addChild(nodeC); // C's ref count == 1
      nodeA = NULL;
      // A's ref count == 0
      // A is deleted, thus also it's std::vector< ref<TreeNode> > mChildNodes is deleted
      // B and C ref count reaches 0 too, so they are also deleted.
    }

The above code shows a bare-bone implementation of a tree-like data structure. As you can see when child nodes are added to a node their reference count is incremented. When the parent is destroyed though, there is no need to iterate recursively over the child nodes to explicitly deallocate them, since they are automatically deallocated if nobody else is referencing them! As you can see this approach can greatly simplify the management of dynamic objects. Reference counting can at the same time simplify our programs and make them more robust, but they must be used carefully to avoid a well known issue called "cyclic dependencies".

Cyclic dependencies

To understand the problem of cyclic dependencies let's see another example:

    class TreeNode: public vl::Object
    {
    public:
      TreeNode(const std::string& name): mName(name) {}

      void addChild(TreeNode* child)
      {
        child->mParent = this;
        mChildNodes.push_back(child);
      }

      void removeChild(int i)
      {
        mChildNodes[i]->mParent = NULL;
        mChildNodes.erase(mChildNodes.begin()+i);
      }

    public:
      std::vector< vl::ref<TreeNode> > mChildNodes; // ref<> pointer
      vl::ref<TreeNode> mParent; // ref<> pointer (BAD)
      std::string mName;
    };

    void mytree()
    {
      vl::ref<TreeNode> nodeA = new TreeNode("A"); // A's ref count == 1
      TreeNode* nodeB = new TreeNode("B"); // B's ref count == 0
      TreeNode* nodeC = new TreeNode("C"); // C's ref count == 0
      nodeA->addChild(nodeB); // B's ref count == 1, A's ref count = 2
      nodeA->addChild(nodeC); // C's ref count == 1, A's ref count = 3
      nodeA = NULL;
      // A's ref count == 2
      // A is NOT deleted!
      // B and C are NOT deleted either!
      // when this function exits we have a memory leak!
    }

So what is the problem here? The problem is that A refers B and C, while at the same time B and C also refer A. So when the the function exits none of their reference count reach zero and we generated a memory leak! In order to manage this kind of cyclic dependency usually one has to define a "who owns who" policy. The owner of another object uses `ref<>` while the owned object uses a normal naked pointer, for example the following data structure does not generate memory leaks:

    class TreeNode: public vl::Object
    {
    public:
      TreeNode(const std::string& name): mName(name) {}

      void addChild(TreeNode* child)
      {
        child->mParent = this;
        mChildNodes.push_back(child);
      }

      void removeChild(int i)
      {
        mChildNodes[i]->mParent = NULL;
        mChildNodes.erase(mChildNodes.begin()+i);
      }

    public:
      std::vector< vl::ref<TreeNode> > mChildNodes; // ref<> pointer
      TreeNode* mParent; // naked pointer!
      std::string mName;
    };

    void mytree()
    {
      vl::ref<TreeNode> nodeA = new TreeNode("A"); // A's ref count == 1
      TreeNode* nodeB = new TreeNode("B"); // B's ref count == 0
      TreeNode* nodeC = new TreeNode("C"); // C's ref count == 0
      nodeA->addChild(nodeB); // B's ref count == 1, A's ref count = 1
      nodeA->addChild(nodeC); // C's ref count == 1, A's ref count = 1
      nodeA = NULL;
      // A's ref count == 0, so the whole tree is deleted as expected
    }

As far as the `mParent` pointer is kept consistent this approach works very well and without any additional complication.

If the `mParent` pointer is not kept consistent it means that the program has a bug. In this case it does not matter if you are using smart pointers or not, your application is doomed to crash sooner or later.

Let's see another example:

    class List: public vl::Object
    {
    public:
      int Data;
      vl::ref<List> mNext;
    };

    void mylist()
    {
      List* a = new List; // a's ref count = 0
      List* b = new List; // b's ref count = 0
      List* c = new List; // c's ref count = 0
      List* d = new List; // d's ref count = 0
      a->mNext = b; // b's ref count = 1
      b->mNext = c; // c's ref count = 1
      c->mNext = d; // d's ref count = 1
      d->mNext = a; // a's ref count = 1
      // now we have a cyclic dependency: a -> b -> c -> d -> a!
      // when we exit this function a, b, c and d are
      // not released since their reference count is 1!
    }

Also in this case the cyclic dependency generated a memory leak since the object were not deallocated as you might have expected.

In this case you must be aware of the cyclic dependency and must break it explicitly when appropriate. In our case we would put something like `a->mNext=NULL`; before the end of the function. This would generate a chain-reaction whose effect whould be the deallocation of the objects in the following order: `b`, `c`, `d`, `a`.

The bottonline is that smart pointers can be very handy and can simplify a lot your life, but you still need to design appropriately your data-structures.

Returning naked pointers

A typical mistake is creating a referenced object within a function and returning the naked pointer instead of the `ref<>` object. Consider the following example:

    MyObject* createMyObject()
    {
      vl::ref<MyObject> obj = new MyObject;
      return obj.get();
    }

The problem here is that when `ref_obj` goes out of scope it will deallocate the object, so the returned pointer will point to an invalid memory address! A way to solve the problem could be substituting the first line of the function with a naked pointer:

    MyObject* createMyObject()
    {
      MyObject* obj = new MyObject;
      return obj;
    }

Although correct, this approach is considered bad practice since this breaks the policy that for each `new` there should be a corresponding `ref<>`, plus the function signature seem to imply that somebody else is owning the object that has just been allocated.

The policy followed by Visualization Library in this cases is to return the actual `ref<>` object to remark the fact that the function is creating a new object and is passing the ownership of such object to you:

    vl::ref<MyObject> createMyObject()
    {
      vl::ref<MyObject> obj = new MyObject;
      return obj;
    }

This approach also prevent other functions to deallocate the object before it is returned as described in the following section.

Passing naked pointers

Let's take the simple example seen above with a slight modification: before returning we do some kind of operation on the object:

    void doSomething(MyObject*);

    vl::ref<MyObject> createMyObject()
    {
      MyObject* obj = new MyObject; // naked pointer! (BAD)
      doSomething(obj);
      return obj;
    }

We have a problem here. What happens if the function `doSomething()` internally uses a `ref<>` to reference the pointer we just passed? Or what happens if the function `doSomething()` internally uses directly or indirectly some object that create a `ref<>` to the pointer we just passed? The answer is that by the time `doSomething()` returns `obj` might contain an invalid pointer since the object it is pointing to might have been already deallocated!

For this reason especially in this cases it is very important to associate the `ref<>` pointer to an object as soon as it is allocated, like this:

    void doSomething(MyObject*);

    vl::ref<MyObject> createMyObject()
    {
      vl::ref<MyObject> obj = new MyObject;
      doSomething(obj.get());
      return obj.get();
    }

Preventing such errors is very simple, you just have to remember that for each `new` there must be a corresponding `ref<>`.

Static allocation and arrays

Sometimes you don't want to dynamically allocate your objects (usually for performance reasons) but still want to safely pass around pointers and `ref<>` references to them. Normally you are not allowed to do this, for example the following example will produce a crash:

    void myfunc()
    {
      MyObject obj; // MyObject is a subclass of vl::Object
      vl::ref<MyObject> obj_ref = &obj; // fear the "&" opearator!
    }
    // when 'obj_ref' goes out of scope it will try to use the 'delete' operator to deallocate the
    // object it points to (which is a statically allocated): your program will crash immediately!

Whenever you use the "&" operator with an object derived from vl::Object you should reconsider why you need to use it.

In order to make `ref<>` work with statically allocated objects you have to disable the automatic object deletion using the method `vl::Object::setAutomaticDelete(bool)` passing `false`. If vl::Object::automaticDelete() is set to `false` then `ref<>` will not delete the object when its reference count reaches zero.

The `vl::Object::setAutomaticDelete()` method can also be useful when you want to allocate a large amount of object in a single chunk using the `new`[] operator. For example if you wanted to quickly allocate a large amount of objects and safely pass pointers to them you would do something like this:

    class MyObjectPool
    {
    public:
      MyObjectPool(): mPool(NULL) {}
      ~MyObjectPool()
      {
        // dispose old pool
        if (mPool)
          delete [] mPool;
      }

      void allocatePool(int count)
      {
        // dispose old pool
        if (mPool)
          delete [] mPool;
        // allocate new pool
        mPool = new MyObject[count];
        // disable the automatic object deletion
        for(int i=0; i<count; ++i)
          mPool->setAutomaticDelete(false);
      }

      // the pointer returned here can be safely used also by ref<>
      MyObject* getObject(int index) { return &mPool[index]; }

    public:
      MyObject* mPool;
    };

Beware that if you disable the automatic deletion for an object you are responsible for tracking all its references and its deletion. In particular pay attention not to deallocate your pool while orther objects are still pointing to data within the pool. If instead of using the new[]/delete[] operator you want to use the `std::vector<>` class, keep in mind that any `push_back()`, `resize()` etc. might reallocate the whole internal buffer kept by `std::vector<>`, thus invalidating all the previously used pointers to the contained objects.

You should use vl::Object::setAutomaticDelete() very carefully and only after excluding all the other options. Usually it is worth using it only in extreme situations, when you have to allocate quickly several hundreds of thousands of complex objects.

References

For more information see also:

- http://en.wikipedia.org/wiki/Smart_pointer
- http://www.boost.org/doc/libs/1_38_0/libs/smart_ptr/smart_ptr.htm

Visualization Library v2009.08 Reference Documentation
Copyright 2005-2009 Michele Bosi. All rights reserved.
Updated on Sun Nov 29 11:11:41 2009.
Permission is granted to use this page to write and publish articles regarding Visualization Library.