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

#include "cvstd.hpp"

Inheritance diagram for cv::Ptr< T >:

[legend]

Public Types
typedef T	element_type
	Generic programming support. More...

Public Member Functions
	Ptr ()
	The default constructor creates a null Ptr - one that owns and stores a null pointer. More...

template<typename Y >
	Ptr (Y *p)
	If p is null, these are equivalent to the default constructor. More...

template<typename Y , typename D >
	Ptr (Y *p, D d)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

	Ptr (const Ptr &o)
	These constructors create a Ptr that shares ownership with another Ptr - that is, own the same pointer as o. More...

template<typename Y >
	Ptr (const Ptr< Y > &o)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

template<typename Y >
	Ptr (const Ptr< Y > &o, T *p)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

	~Ptr ()
	The destructor is equivalent to calling Ptr::release. More...

template<typename Y >
Ptr< Y >	constCast () const
	Ditto for const_cast. More...

template<typename Y >
Ptr< Y >	dynamicCast () const
	Ditto for dynamic_cast. More...

bool	empty () const
	ptr.empty() is equivalent to `!ptr.get()`. More...

T *	get () const
	Returns the stored pointer. More...

	operator T * () const
	Equivalent to get(). More...

detail::RefOrVoid< T >::type	operator* () const
	Ordinary pointer emulation. More...

T *	operator-> () const
	Ordinary pointer emulation. More...

Ptr &	operator= (const Ptr &o)
	Assignment replaces the current Ptr instance with one that owns and stores same pointers as o and then destroys the old instance. More...

template<typename Y >
Ptr &	operator= (const Ptr< Y > &o)

void	release ()
	If no other Ptr instance owns the owned pointer, deletes it with the associated deleter. More...

template<typename Y >
void	reset (Y *p)
	`ptr.reset(...)` is equivalent to `ptr = Ptr<T>(...)`. More...

template<typename Y , typename D >
void	reset (Y *p, D d)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

template<typename Y >
Ptr< Y >	staticCast () const
	Returns a Ptr that owns the same pointer as this, and stores the same pointer as this, except converted via static_cast to Y*. More...

void	swap (Ptr &o)
	Swaps the owned and stored pointers (and deleters, if any) of this and o. More...

Friends
template<typename Y >
struct	Ptr

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 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.

Examples:: houghlines.cpp, lsd_lines.cpp, and segment_objects.cpp.

Member Typedef Documentation

template<typename T>

typedef T cv::Ptr< T >::element_type

Generic programming support.

Constructor & Destructor Documentation

template<typename T>

cv::Ptr< T >::Ptr ( )

The default constructor creates a null Ptr - one that owns and stores a null pointer.

template<typename T>

template<typename Y >

cv::Ptr< T >::Ptr ( Y * p )

If p is null, these are equivalent to the default constructor.

Otherwise, these constructors assume ownership of p - that is, the created Ptr owns and stores p and assumes it is the sole owner of it. Don't use them if p is already owned by another Ptr, or else p will get deleted twice. With the first constructor, DefaultDeleter<Y>() becomes the associated deleter (so p will eventually be deleted with the standard delete operator). Y must be a complete type at the point of invocation. With the second constructor, d becomes the associated deleter. Y* must be convertible to T*.

Parameters

p	Pointer to own.

Note: It is often easier to use makePtr instead.

template<typename T>

template<typename Y , typename D >

cv::Ptr< T >::Ptr	(	Y *	p,
		D	d
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

d	Deleter to use for the owned pointer.
p	Pointer to own.

template<typename T>

cv::Ptr< T >::Ptr ( const Ptr< T > & o )

These constructors create a Ptr that shares ownership with another Ptr - that is, own the same pointer as o.

With the first two, the same pointer is stored, as well; for the second, Y* must be convertible to T*. With the third, p is stored, and Y may be any type. This constructor allows to have completely unrelated owned and stored pointers, and should be used with care to avoid confusion. A relatively benign use is to create a non-owning Ptr, like this:

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

Parameters

o	Ptr to share ownership with.

template<typename T>

template<typename Y >

cv::Ptr< T >::Ptr ( const Ptr< Y > & o )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

o	Ptr to share ownership with.

template<typename T>

template<typename Y >

cv::Ptr< T >::Ptr	(	const Ptr< Y > &	o,
		T *	p
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

o	Ptr to share ownership with.
p	Pointer to store.

template<typename T>

cv::Ptr< T >::~Ptr ( )

The destructor is equivalent to calling Ptr::release.

Member Function Documentation

template<typename T>

template<typename Y >

Ptr<Y> cv::Ptr< T >::constCast ( ) const

Ditto for const_cast.

template<typename T>

template<typename Y >

Ptr<Y> cv::Ptr< T >::dynamicCast ( ) const

Ditto for dynamic_cast.

template<typename T>

bool cv::Ptr< T >::empty ( ) const

ptr.empty() is equivalent to !ptr.get().

Referenced by cv::Algorithm::load(), cv::Algorithm::loadFromString(), cv::Algorithm::read(), and cv::ml::StatModel::train().

Here is the caller graph for this function:

template<typename T>

T* cv::Ptr< T >::get ( ) const

Returns the stored pointer.

template<typename T>

cv::Ptr< T >::operator T * ( ) const

Equivalent to get().

template<typename T>

detail::RefOrVoid<T>::type cv::Ptr< T >::operator* ( ) const

Ordinary pointer emulation.

template<typename T>

T* cv::Ptr< T >::operator-> ( ) const

Ordinary pointer emulation.

template<typename T>

Ptr& cv::Ptr< T >::operator= ( const Ptr< T > & o )

Assignment replaces the current Ptr instance with one that owns and stores same pointers as o and then destroys the old instance.

Parameters

o	Ptr to share ownership with.

template<typename T>

template<typename Y >

Ptr& cv::Ptr< T >::operator= ( const Ptr< Y > & o )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename T>

void cv::Ptr< T >::release ( )

If no other Ptr instance owns the owned pointer, deletes it with the associated deleter.

Then sets both the owned and the stored pointers to NULL.

template<typename T>

template<typename Y >

void cv::Ptr< T >::reset ( Y * p )

ptr.reset(...) is equivalent to ptr = Ptr<T>(...).

Parameters

p	Pointer to own.

template<typename T>

template<typename Y , typename D >

void cv::Ptr< T >::reset	(	Y *	p,
		D	d
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

d	Deleter to use for the owned pointer.
p	Pointer to own.

template<typename T>

template<typename Y >

Ptr<Y> cv::Ptr< T >::staticCast ( ) const

Returns a Ptr that owns the same pointer as this, and stores the same pointer as this, except converted via static_cast to Y*.

template<typename T>

void cv::Ptr< T >::swap ( Ptr< T > & o )

Swaps the owned and stored pointers (and deleters, if any) of this and o.

Parameters

o	Ptr to swap with.

Friends And Related Function Documentation

template<typename T>

template<typename Y >

friend struct Ptr

friend

The documentation for this struct was generated from the following file:

core/include/opencv2/core/cvstd.hpp

Public Types

Public Member Functions

Friends

Detailed Description

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

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

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