.. oe:namespace:: OESystem



.. meta::
   :keywords: OESharedPtr, SharedPtr


.. _OESystem_OESharedPtr:

.. oe:class:: OESharedPtr

   .. oe:api::


      template<class T>
      class OESharedPtr

   .. warning::

      This class has been deprecated. Use ``std::shared_ptr`` instead.
      C++ only class. This class is not visible in any other languages.


   This class is a classic `smart pointer
   <http://en.wikipedia.org/wiki/Smart_pointer>`_ used for
   automatically managing the dynamic memory allocated for the object
   ``T``. Explicitly calling ``delete`` is generally frowned upon
   in modern C++ due to the propensity of explicit ``delete`` leading
   to resource leaks and crashes. Deleting memory should be handled
   more automatically by mechanisms like
   :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` and :ref:`OESharedPtr <OESystem_OESharedPtr>`.

   .. hint::

      One of the most important differences to understand between
      :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` and
      :ref:`OESharedPtr <OESystem_OESharedPtr>` is that
      :ref:`OESharedPtr <OESystem_OESharedPtr>` is always usable inside STL
      containers like ``std::vector<OESharedPtr<T> >``.
      :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` can only be used inside STL
      containers if the compiler supports C++11 move
      constructors. Once all common compilers support C++11, the use
      of :ref:`OESharedPtr <OESystem_OESharedPtr>` should be replaced with
      :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` in many cases.

   :ref:`OESharedPtr <OESystem_OESharedPtr>` is designed to mimic the standard
   C++ `std::shared_ptr
   <http://en.cppreference.com/w/cpp/memory/shared_ptr>`_ in
   functionality with some important differences.

   The first and most obvious difference is that
   :ref:`OESharedPtr <OESystem_OESharedPtr>` will compile and work in all
   compilers *OpenEye* supports without having to juggle whether it is
   coming from the ``std`` or ``std::tr1`` namespaces.

   The second key difference between :ref:`OESharedPtr <OESystem_OESharedPtr>`
   and `std::shared_ptr
   <http://en.cppreference.com/w/cpp/memory/shared_ptr>`_ is whether
   ``const`` is maintained when accessing the object being pointed
   to. By default, in order to maintain compatibility with C, C++
   allows non-const access to const pointers. By extension, this same
   rule applied to C++ smart pointers. This leads to very surprising
   behavior like the following:

   .. code-block:: c++

      struct Foo
      {
        int _x;
        void AlterFoo() { _x = 1; }
      };

      struct BarOwnsFoo
      {
        Foo *_foo;
        void AConstMethod() const { _foo->AlterFoo(); }
      };

   Even though ``AConstMethod`` is ``const``, it isn't actually
   logically const. The internals of the class are changing. This
   behavior may seem benign at first, but it has vast implications in
   a library seeking to be thread-safe. The ``const`` on a method
   implies that the method is thread-safe, especially in C++11. In
   order to enforce thread-safety at runtime,
   :ref:`OESharedPtr <OESystem_OESharedPtr>` maintains the "const'ness" of its
   accessor methods. Therefore, the following is actually a compile
   error:

   .. code-block:: c++

      struct Foo
      {
        int _x;
        void AlterFoo() { _x = 1; }
      };

      struct BarOwnsFoo
      {
        OESharedPtr<Foo> _foo;
        void AConstMethod() const { _foo->AlterFoo(); }
      };

   Catching thread-safety problems very early, at compilation, is
   highly desirable for *OpenEye*. Hence the reason to differ from the
   standard smart pointer semantics in this way.

   .. oe:method:: Constructors

      .. oe:api::

         OESharedPtr()
         OESharedPtr(T* ptr)

      Default constructors the pointer to ``NULL``. Or constructs a
      smart pointer around the pointer ``ptr``.

   .. oe:method:: operator*
      :language: c++

      .. oe:api::

         T& operator*()
         const T& operator*() const

      Dereference the smart pointer and return a reference to the held
      object while maintaining ``const`` correctness. Note,
      dereferencing a ``NULL`` pointer is undefined.

   .. oe:method:: operator->
      :language: c++

      .. oe:api::

         T* operator->()
         const T* operator->() const

      Access the pointer held by this smart pointer while maintaining
      ``const`` correctness.

   .. oe:method:: operator T *
      :language: c++

      .. oe:api::

         operator T *()

      Implicit conversion to a pointer to ``T``.

   .. oe:method:: operator const T *
      :language: c++

      .. oe:api::

         operator const T *() const

      Implicit conversion to a pointer to ``const T``.

   .. oe:method:: Get

      .. oe:api::

         T* Get()
         const T* Get() const

      Access the pointer held by this smart pointer while maintaining
      ``const`` correctness.
