generic-library/opencv
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

cv::Ptr description extended.

Browse Source
This commit is contained in:
Alexander 2013-02-17 18:18:12 +04:00 committed by Alexander Smorkalov
parent 39baa2237e
commit 4091eab45e
1 changed files with 110 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
modules/core/doc/basic_structures.rst
View File

@ -418,27 +418,47 @@ Template class for smart reference-counting pointers ::
};
The ``Ptr<_Tp>`` class is a template class that wraps pointers of the corresponding type. It is similar to ``shared_ptr`` that is part of the Boost library (
http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm
) and also part of the `C++0x <http://en.wikipedia.org/wiki/C++0x>`_
standard.
The ``Ptr<_Tp>`` class is a template class that wraps pointers of the corresponding type. It is
similar to ``shared_ptr`` that is part of the Boost library
(http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm) and also part of the
`C++0x <http://en.wikipedia.org/wiki/C++0x>`_ standard.
This class provides the following options:
*
Default constructor, copy constructor, and assignment operator for an arbitrary C++ class or a 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 wrapping a pointer to such a complex object ``TObj`` to ``Ptr<TObj>`` , you automatically get all of the necessary constructors and the assignment operator.
Default constructor, copy constructor, and assignment operator for an arbitrary C++ class
or a 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 wrapping a pointer to such a
complex object ``TObj`` to ``Ptr<TObj>``, 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 ``Ptr<>`` , the overhead is small and independent of the data size.
*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 ``Ptr<>``,
the overhead is small and independent of the data size.
*
Automatic destruction, 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_class_t*`` instead but then you loose the automatic memory management. Again, by using ``Ptr<base_class_t>()`` instead of the raw pointers, you can solve the problem.
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_class_t*``
instead but then you loose the automatic memory management. Again, by using ``Ptr<base_class_t>()``
instead of the raw pointers, you can solve the problem.
The ``Ptr`` class treats the wrapped object as a black box. The reference counter is allocated and managed separately. The only thing the pointer class needs to know about the object is how to deallocate it. This knowledge is encapsulated in the ``Ptr::delete_obj()`` method that is called when the reference counter becomes 0. If the object is a C++ class instance, no additional coding is needed, because the default implementation of this method calls ``delete obj;`` .
However, if the object is deallocated in a different way, the specialized method should be created. For example, if you want to wrap ``FILE`` , the ``delete_obj`` may be implemented as follows: ::
The ``Ptr`` class treats the wrapped object as a black box. The reference counter is allocated and
managed separately. The only thing the pointer class needs to know about the object is how to
deallocate it. This knowledge is encapsulated in the ``Ptr::delete_obj()`` method that is called when
the reference counter becomes 0. If the object is a C++ class instance, no additional coding is
needed, because the default implementation of this method calls ``delete obj;``. However, if the
object is deallocated in a different way, the specialized method should be created. For example,
if you want to wrap ``FILE``, the ``delete_obj`` may be implemented as follows: ::
template<> inline void Ptr<FILE>::delete_obj()
{
@ -456,7 +476,73 @@ However, if the object is deallocated in a different way, the specialized method
// the file will be closed automatically by the Ptr<FILE> destructor.
.. note:: The reference increment/decrement operations are implemented as atomic operations, and therefore it is normally safe to use the classes in multi-threaded applications. The same is true for :ocv:class:`Mat` and other C++ OpenCV classes that operate on the reference counters.
.. note:: The reference increment/decrement operations are implemented as atomic operations,
and therefore it is normally safe to use the classes in multi-threaded applications.
The same is true for :ocv:class:`Mat` and other C++ OpenCV classes that operate on
the reference counters.
Ptr::Ptr
--------
Various Ptr constructors.
.. ocv:function:: Ptr::Ptr()
.. ocv:function:: Ptr::Ptr(_Tp* _obj)
.. ocv:function:: Ptr::Ptr(const Ptr& ptr)
Ptr::~Ptr
---------
The Ptr destructor.
.. ocv:function:: Ptr::~Ptr()
Ptr::operator =
----------------
Assignment operator.
.. ocv:function:: Ptr& Ptr::operator = (const Ptr& ptr)
Decrements own reference counter (with ``release()``) and increments ptr's reference counter.
Ptr::addref
-----------
Increments reference counter.
.. ocv:function:: void Ptr::addref()
Ptr::release
------------
Decrements reference counter; when it becomes 0, ``delete_obj()`` is called.
.. ocv:function:: void Ptr::release()
Ptr::delete_obj
---------------
User-specified custom object deletion operation. By default, ``delete obj;`` is called.
.. ocv:function:: void Ptr::delete_obj()
Ptr::empty
----------
Returns true if obj == 0;
bool empty() const;
Ptr::operator ->
----------------
Provide access to the object fields and methods.
.. ocv:function:: template<typename _Tp> _Tp* Ptr::operator -> ()
.. ocv:function:: template<typename _Tp> const _Tp* Ptr::operator -> () const
Ptr::operator _Tp*
------------------
Returns the underlying object pointer. Thanks to the methods, the ``Ptr<_Tp>`` can be used instead
of ``_Tp*``.
.. ocv:function:: template<typename _Tp> Ptr::operator _Tp* ()
.. ocv:function:: template<typename _Tp> Ptr::operator const _Tp*() const
Mat
---