Ptr< T > Struct Template Reference
[Basic structures]

Template class for smart pointers with shared ownership. More...

#include <cvstd.hpp>

Detailed Description

template<typename T>
struct cv::Ptr< T >

Template class for smart pointers with shared ownership.

A Ptr<T> pretends to be a pointer to an object of type T. Unlike an ordinary pointer, however, the object will be automatically cleaned up once all Ptr instances pointing to it are destroyed.

Ptr is similar to boost::shared_ptr that is part of the Boost library (<http://www.boost.org/doc/libs/release/libs/smart_ptr/shared_ptr.htm>) and std::shared_ptr from the [C++11](http://en.wikipedia.org/wiki/C++11) standard.

This class provides the following advantages:

• Default constructor, copy constructor, and assignment operator for an arbitrary C++ class or C structure. For some objects, like files, windows, mutexes, sockets, and others, a copy constructor or an assignment operator are difficult to define. For some other objects, like complex classifiers in OpenCV, copy constructors are absent and not easy to implement. Finally, some of complex OpenCV and your own data structures may be written in C. However, copy constructors and default constructors can simplify programming a lot. Besides, they are often required (for example, by STL containers). By using a Ptr to such an object instead of the object itself, you automatically get all of the necessary constructors and the assignment operator.
• *O(1)* complexity of the above-mentioned operations. While some structures, like std::vector, provide a copy constructor and an assignment operator, the operations may take a considerable amount of time if the data structures are large. But if the structures are put into a Ptr, the overhead is small and independent of the data size.
• Automatic and customizable cleanup, even for C structures. See the example below with FILE\*.
• Heterogeneous collections of objects. The standard STL and most other C++ and OpenCV containers can store only objects of the same type and the same size. The classical solution to store objects of different types in the same container is to store pointers to the base class (Base\*) instead but then you lose the automatic memory management. Again, by using Ptr<Base> instead of raw pointers, you can solve the problem.

A Ptr is said to *own* a pointer - that is, for each Ptr there is a pointer that will be deleted once all Ptr instances that own it are destroyed. The owned pointer may be null, in which case nothing is deleted. Each Ptr also *stores* a pointer. The stored pointer is the pointer the Ptr pretends to be; that is, the one you get when you use Ptr::get or the conversion to T\*. It's usually the same as the owned pointer, but if you use casts or the general shared-ownership constructor, the two may diverge: the Ptr will still own the original pointer, but will itself point to something else.

The owned pointer is treated as a black box. The only thing Ptr needs to know about it is how to delete it. This knowledge is encapsulated in the *deleter* - an auxiliary object that is associated with the owned pointer and shared between all Ptr instances that own it. The default deleter is an instance of DefaultDeleter, which uses the standard C++ delete operator; as such it will work with any pointer allocated with the standard new operator.

However, if the pointer must be deleted in a different way, you must specify a custom deleter upon Ptr construction. A deleter is simply a callable object that accepts the pointer as its sole argument. For example, if you want to wrap FILE, you may do so as follows:

    Ptr<FILE> f(fopen("myfile.txt", "w"), fclose);
    if(!f) throw ...;
    fprintf(f, ....);
    ...
    // the file will be closed automatically by f's destructor.

Alternatively, if you want all pointers of a particular type to be deleted the same way, you can specialize DefaultDeleter<T>::operator() for that type, like this:

    namespace cv {
    template<> void DefaultDeleter<FILE>::operator ()(FILE * obj) const
    {
        fclose(obj);
    }
    }

For convenience, the following types from the OpenCV C API already have such a specialization that calls the appropriate release function:

• CvCapture
• CvFileStorage
• CvHaarClassifierCascade
• CvMat
• CvMatND
• CvMemStorage
• CvSparseMat
• CvVideoWriter
• IplImage

  Note:

  The shared ownership mechanism is implemented with reference counting. As such, cyclic ownership (e.g. when object a contains a Ptr to object b, which contains a Ptr to object a) will lead to all involved objects never being cleaned up. Avoid such situations.

  It is safe to concurrently read (but not write) a Ptr instance from multiple threads and therefore it is normally safe to use it in multi-threaded applications. The same is true for Mat and other C++ OpenCV classes that use internal reference counts.

Definition at line 283 of file cvstd.hpp.

Member Typedef Documentation

Constructor & Destructor Documentation

        ptr = Ptr<T>(Ptr<T>(), dont_delete_me); // owns nothing; will not delete the pointer.

Member Function Documentation