Teuchos_RCPDecl.hpp

Go to the documentation of this file.
00001 // @HEADER
00002 // ***********************************************************************
00003 // 
00004 //                    Teuchos: Common Tools Package
00005 //                 Copyright (2004) Sandia Corporation
00006 // 
00007 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
00008 // license for use of this work by or on behalf of the U.S. Government.
00009 // 
00010 // This library is free software; you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as
00012 // published by the Free Software Foundation; either version 2.1 of the
00013 // License, or (at your option) any later version.
00014 //  
00015 // This library is distributed in the hope that it will be useful, but
00016 // WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00018 // Lesser General Public License for more details.
00019 //  
00020 // You should have received a copy of the GNU Lesser General Public
00021 // License along with this library; if not, write to the Free Software
00022 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
00023 // USA
00024 // Questions? Contact Michael A. Heroux (maherou@sandia.gov) 
00025 // 
00026 // ***********************************************************************
00027 // @HEADER
00028 
00029 #ifndef TEUCHOS_RCP_DECL_HPP
00030 #define TEUCHOS_RCP_DECL_HPP
00031 
00032 
00038 #include "Teuchos_RCPNode.hpp"
00039 #include "Teuchos_ENull.hpp"
00040 #include "Teuchos_NullIteratorTraits.hpp"
00041 
00042 
00043 #ifdef REFCOUNTPTR_INLINE_FUNCS
00044 #  define REFCOUNTPTR_INLINE inline
00045 #else
00046 #  define REFCOUNTPTR_INLINE
00047 #endif
00048 
00049 
00050 #ifdef TEUCHOS_DEBUG
00051 #  define TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL
00052 #endif
00053 
00054 
00055 namespace Teuchos {
00056 
00057 
00059 template<class T> class Ptr;
00060 
00061 
00062 enum ERCPWeakNoDealloc { RCP_WEAK_NO_DEALLOC };
00063 enum ERCPUndefinedWeakNoDealloc { RCP_UNDEFINED_WEAK_NO_DEALLOC };
00064 enum ERCPUndefinedWithDealloc { RCP_UNDEFINED_WITH_DEALLOC };
00065 
00066 
00414 template<class T>
00415 class RCP {
00416 public:
00417 
00419   typedef T  element_type;
00420 
00423 
00445   inline RCP(ENull null_arg = null);
00446 
00467   inline explicit RCP( T* p, bool has_ownership = true );
00468 
00490   template<class Dealloc_T>
00491   inline RCP(T* p, Dealloc_T dealloc, bool has_ownership);
00492 
00510   inline RCP(const RCP<T>& r_ptr);
00511 
00525   template<class T2>
00526   inline RCP(const RCP<T2>& r_ptr);
00527 
00539   inline ~RCP();
00540 
00560   inline RCP<T>& operator=(const RCP<T>& r_ptr);
00561 
00574   inline RCP<T>& operator=(ENull);
00575 
00577   inline void swap(RCP<T> &r_ptr);
00578 
00580 
00583 
00585   inline bool is_null() const;
00586 
00593   inline T* operator->() const;
00594 
00601   inline T& operator*() const;
00602 
00607   inline T* get() const;
00608 
00613   inline T* getRawPtr() const;
00614 
00616   inline Ptr<T> ptr() const;
00617 
00619   inline Ptr<T> operator()() const;
00620 
00622   inline RCP<const T> getConst() const;
00623 
00625 
00628 
00640   inline ERCPStrength strength() const;
00641 
00651   inline bool is_valid_ptr() const;
00652 
00658   inline int strong_count() const;
00659 
00665   inline int weak_count() const;
00666 
00668   inline int total_count() const;
00669 
00688   inline void set_has_ownership();
00689 
00700   inline bool has_ownership() const;
00701 
00733   inline Ptr<T> release();
00734 
00751   inline RCP<T> create_weak() const;
00752 
00769   inline RCP<T> create_strong() const;
00770 
00778   template<class T2>
00779   inline bool shares_resource(const RCP<T2>& r_ptr) const;
00780 
00782 
00785 
00789   inline const RCP<T>& assert_not_null() const;
00790 
00800   inline const RCP<T>& assert_valid_ptr() const;
00801 
00803   inline const RCP<T>& debug_assert_not_null() const
00804     {
00805 #ifdef TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL
00806       assert_not_null();
00807 #endif
00808       return *this;
00809     }
00810 
00812   inline const RCP<T>& debug_assert_valid_ptr() const
00813     {
00814 #ifdef TEUCHOS_DEBUG
00815       assert_valid_ptr();
00816 #endif
00817       return *this;
00818     }
00819 
00821 
00824 
00826   inline void reset();
00827 
00838   template<class T2>
00839   inline void reset(T2* p, bool has_ownership = true);
00840 
00842   inline int count() const;
00843 
00845 
00846 private:
00847 
00848   // //////////////////////////////////////////////////////////////
00849   // Private data members
00850 
00851   T *ptr_; // NULL if this pointer is null
00852   RCPNodeHandle node_; // NULL if this pointer is null
00853 
00854 public: // Bad bad bad
00855 
00856   // These constructors are put here because we don't want to confuse users
00857   // who would otherwise see them.
00858 
00870   inline explicit RCP(T* p, ERCPWeakNoDealloc);
00871 
00882   inline explicit RCP(T* p, ERCPUndefinedWeakNoDealloc);
00883 
00890   template<class Dealloc_T>
00891   inline RCP(T* p, Dealloc_T dealloc, ERCPUndefinedWithDealloc,
00892     bool has_ownership = true);
00893 
00894 #ifndef DOXYGEN_COMPILE
00895 
00896   // WARNING: A general user should *never* call these functions!
00897   inline RCP(T* p, const RCPNodeHandle &node);
00898   inline T* access_private_ptr() const; // Does not throw
00899   inline RCPNodeHandle& nonconst_access_private_node(); // Does not thorw
00900   inline const RCPNodeHandle& access_private_node() const; // Does not thorw
00901 
00902 #endif
00903 
00904 };
00905 
00906 
00907 // 2008/09/22: rabartl: NOTE: I removed the TypeNameTraits<RCP<T> >
00908 // specialization since I want to be able to print the type name of an RCP
00909 // that does not have the type T fully defined!
00910 
00911 
00916 template<typename T>
00917 class NullIteratorTraits<RCP<T> > {
00918 public:
00919   static RCP<T> getNull() { return null; }
00920 };
00921 
00922 
00927 template<class T>
00928 class DeallocNull
00929 {
00930 public:
00932   typedef T ptr_t;
00934   void free( T* ptr ) { }
00935 };
00936 
00937 
00943 template<class T>
00944 class DeallocDelete
00945 {
00946 public:
00948   typedef T ptr_t;
00950   void free( T* ptr ) { if(ptr) delete ptr; }
00951 };
00952 
00953 
00959 template<class T>
00960 class DeallocArrayDelete
00961 {
00962 public:
00964   typedef T ptr_t;
00966   void free( T* ptr ) { if(ptr) delete [] ptr; }
00967 };
00968 
00969 
00982 template<class T, class DeleteFunctor>
00983 class DeallocFunctorDelete
00984 {
00985 public:
00986   DeallocFunctorDelete( DeleteFunctor deleteFunctor ) : deleteFunctor_(deleteFunctor) {}
00987   typedef T ptr_t;
00988   void free( T* ptr ) { if(ptr) deleteFunctor_(ptr); }
00989 private:
00990   DeleteFunctor deleteFunctor_;
00991   DeallocFunctorDelete(); // Not defined and not to be called!
00992 };
00993 
00994 
00999 template<class T, class DeleteFunctor>
01000 DeallocFunctorDelete<T,DeleteFunctor>
01001 deallocFunctorDelete( DeleteFunctor deleteFunctor )
01002 {
01003   return DeallocFunctorDelete<T,DeleteFunctor>(deleteFunctor);
01004 }
01005 
01006 
01020 template<class T, class DeleteHandleFunctor>
01021 class DeallocFunctorHandleDelete
01022 {
01023 public:
01024   DeallocFunctorHandleDelete( DeleteHandleFunctor deleteHandleFunctor )
01025     : deleteHandleFunctor_(deleteHandleFunctor) {}
01026   typedef T ptr_t;
01027   void free( T* ptr ) { if(ptr) { T **hdl = &ptr; deleteHandleFunctor_(hdl); } }
01028 private:
01029   DeleteHandleFunctor deleteHandleFunctor_;
01030   DeallocFunctorHandleDelete(); // Not defined and not to be called!
01031 };
01032 
01033 
01038 template<class T, class DeleteHandleFunctor>
01039 DeallocFunctorHandleDelete<T,DeleteHandleFunctor>
01040 deallocFunctorHandleDelete( DeleteHandleFunctor deleteHandleFunctor )
01041 {
01042   return DeallocFunctorHandleDelete<T,DeleteHandleFunctor>(deleteHandleFunctor);
01043 }
01044 
01045 
01054 template<class T, class Embedded, class Dealloc>
01055 class EmbeddedObjDealloc
01056 {
01057 public:
01058   typedef typename Dealloc::ptr_t ptr_t;
01059   EmbeddedObjDealloc(
01060     const Embedded &embedded, EPrePostDestruction prePostDestroy,
01061     Dealloc dealloc
01062     ) : embedded_(embedded), prePostDestroy_(prePostDestroy), dealloc_(dealloc)
01063     {}
01064   void setObj( const Embedded &embedded ) { embedded_ = embedded; }
01065   const Embedded& getObj() const { return embedded_; }
01066   Embedded& getNonconstObj() { return embedded_; }
01067   void free( T* ptr )
01068     {
01069       if (prePostDestroy_ == PRE_DESTROY)
01070         embedded_ = Embedded();
01071       dealloc_.free(ptr);
01072       if (prePostDestroy_ == POST_DESTROY)
01073         embedded_ = Embedded();
01074     }
01075 private:
01076   Embedded embedded_;
01077   EPrePostDestruction prePostDestroy_;
01078   Dealloc dealloc_;
01079   EmbeddedObjDealloc(); // Not defined and not to be called!
01080 };
01081 
01082 
01087 template<class T, class Embedded >
01088 EmbeddedObjDealloc<T,Embedded,DeallocDelete<T> >
01089 embeddedObjDeallocDelete(const Embedded &embedded, EPrePostDestruction prePostDestroy)
01090 {
01091   return EmbeddedObjDealloc<T,Embedded,DeallocDelete<T> >(
01092     embedded, prePostDestroy,DeallocDelete<T>());
01093 }
01094 
01095 
01100 template<class T, class Embedded >
01101 EmbeddedObjDealloc<T,Embedded,DeallocArrayDelete<T> >
01102 embeddedObjDeallocArrayDelete(const Embedded &embedded, EPrePostDestruction prePostDestroy)
01103 {
01104   return EmbeddedObjDealloc<T,Embedded,DeallocArrayDelete<T> >(
01105     embedded, prePostDestroy,DeallocArrayDelete<T>());
01106 }
01107 
01108 
01131 template<class T> inline
01132 RCP<T> rcp(T* p, bool owns_mem = true);
01133 
01134 
01178 template<class T, class Dealloc_T> inline
01179 RCP<T> rcpWithDealloc(T* p, Dealloc_T dealloc, bool owns_mem=true);
01180 
01181 
01183 template<class T, class Dealloc_T> inline
01184 RCP<T> rcp( T* p, Dealloc_T dealloc, bool owns_mem )
01185 {
01186   return rcpWithDealloc(p, dealloc, owns_mem);
01187 }
01188 
01189 
01201 template<class T, class Dealloc_T> inline
01202 RCP<T> rcpWithDeallocUndef(T* p, Dealloc_T dealloc, bool owns_mem=true);
01203 
01204 
01214 template<class T> inline
01215 RCP<T> rcpFromRef(T& r);
01216 
01217 
01227 template<class T> inline
01228 RCP<T> rcpFromUndefRef(T& r);
01229 
01230 
01231 /* \brief Create an RCP with and also put in an embedded object.
01232  *
01233  * In this case the embedded object is destroyed (by setting to Embedded())
01234  * before the object at <tt>*p</tt> is destroyed.
01235  *
01236  * The embedded object can be extracted using <tt>getEmbeddedObj()</tt> and
01237  * <tt>getNonconstEmbeddedObject()</tt>.
01238  *
01239  * \relates RCP
01240  */
01241 template<class T, class Embedded> inline
01242 RCP<T>
01243 rcpWithEmbeddedObjPreDestroy( T* p, const Embedded &embedded, bool owns_mem = true );
01244 
01245 
01246 /* \brief Create an RCP with and also put in an embedded object.
01247  *
01248  * In this case the embedded object is destroyed (by setting to Embedded())
01249  * after the object at <tt>*p</tt> is destroyed.
01250  *
01251  * The embedded object can be extracted using <tt>getEmbeddedObj()</tt> and
01252  * <tt>getNonconstEmbeddedObject()</tt>.
01253  *
01254  * \relates RCP
01255  */
01256 template<class T, class Embedded> inline
01257 RCP<T>
01258 rcpWithEmbeddedObjPostDestroy( T* p, const Embedded &embedded, bool owns_mem = true );
01259 
01260 
01261 /* \brief Create an RCP with and also put in an embedded object.
01262  *
01263  * This function should be called when it is not important when the embedded
01264  * object is destroyed (by setting to Embedded()) with respect to when
01265  * <tt>*p</tt> is destroyed.
01266  *
01267  * The embedded object can be extracted using <tt>getEmbeddedObj()</tt> and
01268  * <tt>getNonconstEmbeddedObject()</tt>.
01269  *
01270  * \relates RCP
01271  */
01272 template<class T, class Embedded> inline
01273 RCP<T>
01274 rcpWithEmbeddedObj( T* p, const Embedded &embedded, bool owns_mem = true );
01275 
01276 
01277 // 2007/10/25: rabartl: ToDo: put in versions of
01278 // rcpWithEmbedded[Pre,Post]DestoryWithDealloc(...) that also accept a general
01279 // deallocator!
01280 
01281 
01289 template<class T, class ParentT>
01290 RCP<T> rcpWithInvertedObjOwnership(const RCP<T> &child, const RCP<ParentT> &parent);
01291 
01292 
01297 template<class T> inline
01298 bool is_null( const RCP<T> &p );
01299 
01300 
01305 template<class T> inline
01306 bool nonnull( const RCP<T> &p );
01307 
01308 
01313 template<class T> inline
01314 bool operator==( const RCP<T> &p, ENull );
01315 
01316 
01321 template<class T> inline
01322 bool operator!=( const RCP<T> &p, ENull );
01323 
01324 
01330 template<class T1, class T2> inline
01331 bool operator==( const RCP<T1> &p1, const RCP<T2> &p2 );
01332 
01333 
01339 template<class T1, class T2> inline
01340 bool operator!=( const RCP<T1> &p1, const RCP<T2> &p2 );
01341 
01342 
01352 template<class T2, class T1> inline
01353 RCP<T2> rcp_implicit_cast(const RCP<T1>& p1);
01354 
01355 
01366 template<class T2, class T1> inline
01367 RCP<T2> rcp_static_cast(const RCP<T1>& p1);
01368 
01369 
01376 template<class T2, class T1> inline
01377 RCP<T2> rcp_const_cast(const RCP<T1>& p1);
01378 
01379 
01403 template<class T2, class T1> inline
01404 RCP<T2> rcp_dynamic_cast(
01405   const RCP<T1>& p1, bool throw_on_fail = false
01406   );
01407 
01408 
01467 template<class T1, class T2>
01468 void set_extra_data( const T1 &extra_data, const std::string& name,
01469   const Ptr<RCP<T2> > &p, EPrePostDestruction destroy_when = POST_DESTROY,
01470   bool force_unique = true);
01471 
01491 template<class T1, class T2>
01492 const T1& get_extra_data( const RCP<T2>& p, const std::string& name );
01493 
01494 
01514 template<class T1, class T2>
01515 T1& get_nonconst_extra_data( RCP<T2>& p, const std::string& name );
01516 
01517 
01542 template<class T1, class T2>
01543 Ptr<const T1> get_optional_extra_data( const RCP<T2>& p, const std::string& name );
01544 
01545 
01570 template<class T1, class T2>
01571 Ptr<T1> get_optional_nonconst_extra_data( RCP<T2>& p, const std::string& name );
01572 
01573 
01585 template<class Dealloc_T, class T>
01586 const Dealloc_T& get_dealloc( const RCP<T>& p );
01587 
01588 
01600 template<class Dealloc_T, class T>
01601 Dealloc_T& get_nonconst_dealloc( const RCP<T>& p );
01602 
01603 
01618 template<class Dealloc_T, class T>
01619 Ptr<const Dealloc_T> get_optional_dealloc( const RCP<T>& p );
01620 
01621 
01636 template<class Dealloc_T, class T>
01637 Ptr<Dealloc_T> get_optional_nonconst_dealloc( const RCP<T>& p );
01638 
01639 
01646 template<class TOrig, class Embedded, class T>
01647 const Embedded& getEmbeddedObj( const RCP<T>& p );
01648 
01649 
01656 template<class TOrig, class Embedded, class T>
01657 Embedded& getNonconstEmbeddedObj( const RCP<T>& p );
01658 
01659 
01666 template<class TOrig, class Embedded, class T>
01667 Ptr<const Embedded> getOptionalEmbeddedObj( const RCP<T>& p );
01668 
01669 
01676 template<class TOrig, class Embedded, class T>
01677 Ptr<Embedded> getOptionalNonconstEmbeddedObj( const RCP<T>& p );
01678 
01679 
01685 template<class ParentT, class T>
01686 RCP<ParentT> getInvertedObjOwnershipParent(const RCP<T> &invertedChild);
01687 
01688 
01696 template<class T>
01697 std::ostream& operator<<( std::ostream& out, const RCP<T>& p );
01698 
01699 
01700 } // end namespace Teuchos
01701 
01702 
01703 #endif  // TEUCHOS_RCP_DECL_HPP

Generated on Tue Jul 13 09:22:59 2010 for Teuchos - Trilinos Tools Package by  doxygen 1.4.7