OpenCV
3.0.0
Open Source Computer Vision
|
Template class for smart pointers with shared ownership. More...
#include "cvstd.hpp"
Public Types | |
typedef T | element_type |
Public Member Functions | |
Ptr () | |
template<typename Y > | |
Ptr (Y *p) | |
template<typename Y , typename D > | |
Ptr (Y *p, D d) | |
Ptr (const Ptr &o) | |
template<typename Y > | |
Ptr (const Ptr< Y > &o) | |
template<typename Y > | |
Ptr (const Ptr< Y > &o, T *p) | |
~Ptr () | |
template<typename Y > | |
Ptr< Y > | constCast () const |
template<typename Y > | |
Ptr< Y > | dynamicCast () const |
bool | empty () const |
T * | get () const |
operator T * () const | |
detail::RefOrVoid< T >::type | operator* () const |
T * | operator-> () const |
Ptr & | operator= (const Ptr &o) |
template<typename Y > | |
Ptr & | operator= (const Ptr< Y > &o) |
void | release () |
template<typename Y > | |
void | reset (Y *p) |
template<typename Y , typename D > | |
void | reset (Y *p, D d) |
template<typename Y > | |
Ptr< Y > | staticCast () const |
void | swap (Ptr &o) |
Friends | |
template<typename Y > | |
struct | Ptr |
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:
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:
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:
For convenience, the following types from the OpenCV C API already have such a specialization that calls the appropriate release function:
typedef T cv::Ptr< T >::element_type |
Generic programming support.
The default constructor creates a null Ptr - one that owns and stores a null pointer.
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*.
p | Pointer to own. |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
d | Deleter to use for the owned pointer. |
p | Pointer to own. |
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:
o | Ptr to share ownership with. |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
o | Ptr to share ownership with. |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
o | Ptr to share ownership with. |
p | Pointer to store. |
The destructor is equivalent to calling Ptr::release.
Ditto for const_cast.
Ditto for dynamic_cast.
T* cv::Ptr< T >::get | ( | ) | const |
Returns the stored pointer.
detail::RefOrVoid<T>::type cv::Ptr< T >::operator* | ( | ) | const |
Ordinary pointer emulation.
T* cv::Ptr< T >::operator-> | ( | ) | const |
Ordinary pointer emulation.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
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.
ptr.reset(...)
is equivalent to ptr = Ptr<T>(...)
.
p | Pointer to own. |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
d | Deleter to use for the owned pointer. |
p | Pointer to own. |
Returns a Ptr that owns the same pointer as this, and stores the same pointer as this, except converted via static_cast to Y*.
Swaps the owned and stored pointers (and deleters, if any) of this and o.
o | Ptr to swap with. |