Memory Management
=================

.. highlight:: cpp


When using the new interface, the most of memory deallocation and even memory allocation operations are done automatically when needed.

First of all, 
:ref:`Mat`
, 
:ref:`SparseMat`
and other classes have destructors
that deallocate memory buffers occupied by the structures when needed.

Secondly, this "when needed" means that the destructors do not always deallocate the buffers, they take into account possible data sharing.
That is, in a destructor the reference counter associated with the underlying data is decremented and the data is deallocated
if and only if the reference counter becomes zero, that is, when no other structures refer to the same buffer. When such a structure
containing a reference counter is copied, usually just the header is duplicated, while the underlying data is not; instead, the reference counter is incremented to memorize that there is another owner of the same data.
Also, some structures, such as 
``Mat``
, can refer to the user-allocated data.
In this case the reference counter is 
``NULL``
pointer and then no reference counting is done - the data is not deallocated by the destructors and should be deallocated manually by the user. We saw this scheme in the first example in the chapter:



::


    
    // allocates IplImages and wraps it into shared pointer class.
    Ptr<IplImage> iplimg = cvLoadImage(...);
    
    // constructs Mat header for IplImage data;
    // does not copy the data;
    // the reference counter will be NULL
    Mat img(iplimg);
    ...
    // in the end of the block img destructor is called,
    // which does not try to deallocate the data because
    // of NULL pointer to the reference counter.
    //
    // Then Ptr<IplImage> destructor is called that decrements
    // the reference counter and, as the counter becomes 0 in this case,
    // the destructor calls cvReleaseImage().
    

..

The copying semantics was mentioned in the above paragraph, but deserves a dedicated discussion.
By default, the new OpenCV structures implement shallow, so called O(1) (i.e. constant-time) assignment operations. It gives user possibility to pass quite big data structures to functions (though, e.g. passing 
``const Mat&``
is still faster than passing 
``Mat``
), return them (e.g. see the example with 
:ref:`findHomography`
above), store them in OpenCV and STL containers etc. - and do all of this very efficiently. On the other hand, most of the new data structures provide 
``clone()``
method that creates a full copy of an object. Here is the sample:



::


    
    // create a big 8Mb matrix
    Mat A(1000, 1000, CV_64F);
    
    // create another header for the same matrix;
    // this is instant operation, regardless of the matrix size.
    Mat B = A;
    // create another header for the 3-rd row of A; no data is copied either
    Mat C = B.row(3);
    // now create a separate copy of the matrix
    Mat D = B.clone();
    // copy the 5-th row of B to C, that is, copy the 5-th row of A 
    // to the 3-rd row of A.
    B.row(5).copyTo(C);
    // now let A and D share the data; after that the modified version
    // of A is still referenced by B and C.
    A = D;
    // now make B an empty matrix (which references no memory buffers),
    // but the modified version of A will still be referenced by C,
    // despite that C is just a single row of the original A
    B.release(); 
                 
    // finally, make a full copy of C. In result, the big modified
    // matrix will be deallocated, since it's not referenced by anyone
    C = C.clone();
    

..

Memory management of the new data structures is automatic and thus easy. If, however, your code uses 
:ref:`IplImage`
,
:ref:`CvMat`
or other C data structures a lot, memory management can still be automated without immediate migration
to 
:ref:`Mat`
by using the already mentioned template class 
:ref:`Ptr`
, similar to 
``shared_ptr``
from Boost and C++ TR1.
It wraps a pointer to an arbitrary object, provides transparent access to all the object fields and associates a reference counter with it.
Instance of the class can be passed to any function that expects the original pointer. For correct deallocation of the object, you should specialize 
``Ptr<T>::delete_obj()``
method. Such specialized methods already exist for the classical OpenCV structures, e.g.:



::


    
    // cxoperations.hpp:
    ...
    template<> inline Ptr<IplImage>::delete_obj() {
        cvReleaseImage(&obj);
    }
    ...
    

..

See 
:ref:`Ptr`
description for more details and other usage scenarios.