// @HEADER // *********************************************************************** // // Teuchos: Common Tools Package // Copyright (2004) Sandia Corporation // // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive // license for use of this work by or on behalf of the U.S. Government. // // Redistribution and use in source and binary forms, with or without // modification, are permitted provided that the following conditions are // met: // // 1. Redistributions of source code must retain the above copyright // notice, this list of conditions and the following disclaimer. // // 2. Redistributions in binary form must reproduce the above copyright // notice, this list of conditions and the following disclaimer in the // documentation and/or other materials provided with the distribution. // // 3. Neither the name of the Corporation nor the names of the // contributors may be used to endorse or promote products derived from // this software without specific prior written permission. // // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. // // Questions? Contact Michael A. Heroux (maherou@sandia.gov) // // *********************************************************************** // @HEADER #ifndef TEUCHOS_RCP_DECL_HPP #define TEUCHOS_RCP_DECL_HPP /*! \file Teuchos_RCPDecl.hpp \brief Reference-counted pointer class and non-member templated function implementations. */ #include "Teuchos_RCPNode.hpp" #include "Teuchos_ENull.hpp" #include "Teuchos_NullIteratorTraits.hpp" #ifdef REFCOUNTPTR_INLINE_FUNCS # define REFCOUNTPTR_INLINE inline #else # define REFCOUNTPTR_INLINE #endif #ifdef TEUCHOS_DEBUG # define TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL #endif namespace Teuchos { /** \brief . */ template class Ptr; enum ERCPWeakNoDealloc { RCP_WEAK_NO_DEALLOC }; enum ERCPUndefinedWeakNoDealloc { RCP_UNDEFINED_WEAK_NO_DEALLOC }; enum ERCPUndefinedWithDealloc { RCP_UNDEFINED_WITH_DEALLOC }; /** \brief Smart reference counting pointer class for automatic garbage collection. For a carefully written discussion about what this class is and basic details on how to use it see the beginners guide. Quickstart for RCP Here we present a short, but fairly comprehensive, quick-start for the use of RCP<>. The use cases described here should cover the overwhelming majority of the use instances of RCP<> in a typical program. The following class hierarchy will be used in the C++ examples given below. \code class A { public: virtual ~A(){} virtual void f(){} }; class B1 : virtual public A {}; class B2 : virtual public A {}; class C : virtual public B1, virtual public B2 {}; class D {}; class E : public D {}; \endcode All of the following code examples used in this quickstart are assumed to be in the namespace Teuchos or have appropriate using Teuchos::... declarations. This removes the need to explicitly use Teuchos:: to qualify classes, functions and other declarations from the Teuchos namespace. Note that some of the runtime checks are denoted as "debug runtime checked" which means that checking will only be performed in a debug build (that is one where the macro TEUCHOS_DEBUG is defined at compile time).

Creation of RCP<> objects
1. Creating an RCP<> object using new \code RCP c_ptr = rcp(new C); \endcode
2. Creating a RCP<> object equipped with a specialized deallocator function : Teuchos::DeallocFunctorDelete \code void someDeallocFunction(C* c_ptr); RCP c_ptr = rcp(new deallocFunctorDelete(someDeallocFunction),true); \endcode
3. Initializing a RCP<> object to NULL \code RCP c_ptr; \endcode or \code RCP c_ptr = null; \endcode
4. Initializing a RCP<> object to an object \underline{not} allocated with new \code C c; RCP c_ptr = rcpFromRef(c); \endcode
5. Copy constructor (implicit casting) \code RCP c_ptr = rcp(new C); // No cast RCP a_ptr = c_ptr; // Cast to base class RCP ca_ptr = a_ptr; // Cast from non-const to const \endcode
6. Representing constantness and non-constantness
  1. Non-constant pointer to non-constant object \code RCP c_ptr; \endcode
  2. Constant pointer to non-constant object \code const RCP c_ptr; \endcode
  3. Non-Constant pointer to constant object \code RCP c_ptr; \endcode
  4. Constant pointer to constant object \code const RCP c_ptr; \endcode
Reinitialization of RCP<> objects (using assignment operator)
Accessing the reference-counted object
1. Access to object reference (debug runtime checked) : Teuchos::RCP::operator*() \code C &c_ref = *c_ptr; \endcode
2. Access to object pointer (unchecked, may return NULL) : Teuchos::RCP::get() \code C *c_rptr = c_ptr.get(); \endcode or \code C *c_rptr = c_ptr.getRawPtr(); \endcode WARNING:: Avoid exposing raw C++ pointers!
3. Access to object pointer (debug runtime checked, will not return NULL) : Teuchos::RCP::operator*() \code C *c_rptr = &*c_ptr; \endcode WARNING:: Avoid exposing raw C++ pointers!
4. Access of object's member (debug runtime checked) : Teuchos::RCP::operator->() \code c_ptr->f(); \endcode
5. Testing for non-null : Teuchos::RCP::get(), Teuchos::operator==(), Teuchos::operator!=() \code if (a_ptr.is_null) std::cout << "a_ptr is not null!\n"; \endcode or \code if (a_ptr != null) std::cout << "a_ptr is not null!\n"; \endcode or
6. Testing for null \code if (!a_ptr.is_null()) std::cout << "a_ptr is null!\n"; \endcode or \code if (a_ptr == null) std::cout << "a_ptr is null!\n"; \endcode or \code if (is_null(a_ptr)) std::cout << "a_ptr is null!\n"; \endcode
Casting
1. Implicit casting (see copy constructor above)
  
  Using copy constructor (see above)
  Using conversion function \code RCP c_ptr = rcp(new C); // No cast RCP a_ptr = rcp_implicit_cast (c_ptr); // To base RCP ca_ptr = rcp_implicit_cast(a_ptr);// To const \endcode
2. Casting away const : rcp_const_cast() \code RCP ca_ptr = rcp(new C); RCP a_ptr = rcp_const_cast (ca_ptr); // cast away const! \endcode
3. Static cast (no runtime check) : rcp_static_cast() \code RCP d_ptr = rcp(new E); RCP e_ptr = rcp_static_cast(d_ptr); // Unchecked, unsafe? \endcode
4. Dynamic cast (runtime checked, failed cast allowed) : rcp_dynamic_cast() \code RCP a_ptr = rcp(new C); RCP b1_ptr = rcp_dynamic_cast(a_ptr); // Checked, safe! RCP b2_ptr = rcp_dynamic_cast(b1_ptr); // Checked, safe! RCP c_ptr = rcp_dynamic_cast(b2_ptr); // Checked, safe! \endcode
5. Dynamic cast (runtime checked, failed cast not allowed) : rcp_dynamic_cast() \code RCP a_ptr1 = rcp(new C); RCP a_ptr2 = rcp(new A); RCP b1_ptr1 = rcp_dynamic_cast(a_ptr1, true); // Success! RCP b1_ptr2 = rcp_dynamic_cast(a_ptr2, true); // Throw std::bad_cast! \endcode
Customized deallocators
1. Creating a RCP<> object with a custom deallocator : rcp() TODO: Update this example!
2. Access customized deallocator (runtime checked, throws on failure) : Teuchos::get_dealloc() \code const MyCustomDealloc &dealloc = get_dealloc >(c_ptr); \endcode
3. Access optional customized deallocator : Teuchos::get_optional_dealloc() \code const Ptr > dealloc = get_optional_dealloc >(c_ptr); if (!is_null(dealloc)) std::cout << "This deallocator exits!\n"; \endcode
Managing extra data
1. Adding extra data (post destruction of extra data) : Teuchos::set_extra_data() \code set_extra_data(rcp(new B1), "A:B1", inOutArg(a_ptr)); \endcode
2. Adding extra data (pre destruction of extra data) : Teuchos::get_extra_data() \code set_extra_data(rcp(new B1),"A:B1", inOutArg(a_ptr), PRE_DESTORY); \endcode
3. Retrieving extra data : Teuchos::get_extra_data() \code get_extra_data >(a_ptr, "A:B1")->f(); \endcode
4. Resetting extra data : Teuchos::get_extra_data() \code get_extra_data >(a_ptr, "A:B1") = rcp(new C); \endcode
5. Retrieving optional extra data : Teuchos::get_optional_extra_data() \code const Ptr > b1 = get_optional_extra_data >(a_ptr, "A:B1"); if (!is_null(b1)) (*b1)->f(); \endcode

\ingroup teuchos_mem_mng_grp */ template class RCP { public: /** \brief . */ typedef T element_type; /** \name Constructors/destructors/initializers. */ //@{ /** \brief Initialize RCP to NULL. * * Postconditons:

this->get() == 0 *
this->strength() == RCP_STRENGTH_INVALID *
this->is_vali_ptr() == true *
this->strong_count() == 0 *
this->weak_count() == 0 *
this->has_ownership() == false *

* * This allows clients to write code like: \code RCP p = null; \endcode or \code RCP p; \endcode * and construct to NULL */ inline RCP(ENull null_arg = null); /** \brief Construct from a raw pointer. * * Note that this constructor is declared explicit so there is no implicit * conversion from a raw pointer to an RCP allowed. If * has_ownership==false, then no attempt to delete the object will * occur. * * Postconditons:

this->get() == p *
this->strength() == RCP_STRONG *
this->is_vali_ptr() == true *
this->strong_count() == 1 *
this->weak_count() == 0 *
this->has_ownership() == has_ownership *

* * NOTE: It is recommended that this constructor never be called directly * but only through a type-specific non-member constructor function or at * least through the general non-member rcp() function. */ inline explicit RCP( T* p, bool has_ownership = true ); /** \brief Construct from a raw pointer and a custom deallocator. * * \param p [in] Pointer to the reference-counted object to be wrapped * * \param dealloc [in] Deallocator policy object that will be copied by * value and will perform the custom deallocation of the object pointed to * by p when the last RCP object goes away. See the class * DeallocDelete for the specfication and behavior of this policy * interface. * * Postconditons:

this->get() == p *
this->strength() == RCP_STRONG *
this->is_vali_ptr() == true *
this->strong_count() == 1 *
this->weak_count() == 0 *
this->has_ownership() == has_ownership *
get_dealloc(*this) returns a copy of the * custom deallocator object dealloc>/tt>. *