Teuchos - Trilinos Tools Package  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Teuchos_RCPDecl.hpp
Go to the documentation of this file.
1 // @HEADER
2 // ***********************************************************************
3 //
4 // Teuchos: Common Tools Package
5 // Copyright (2004) Sandia Corporation
6 //
7 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
8 // license for use of this work by or on behalf of the U.S. Government.
9 //
10 // Redistribution and use in source and binary forms, with or without
11 // modification, are permitted provided that the following conditions are
12 // met:
13 //
14 // 1. Redistributions of source code must retain the above copyright
15 // notice, this list of conditions and the following disclaimer.
16 //
17 // 2. Redistributions in binary form must reproduce the above copyright
18 // notice, this list of conditions and the following disclaimer in the
19 // documentation and/or other materials provided with the distribution.
20 //
21 // 3. Neither the name of the Corporation nor the names of the
22 // contributors may be used to endorse or promote products derived from
23 // this software without specific prior written permission.
24 //
25 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
26 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
29 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
32 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
33 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
34 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
35 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 //
37 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
38 //
39 // ***********************************************************************
40 // @HEADER
41 
42 #ifndef TEUCHOS_RCP_DECL_HPP
43 #define TEUCHOS_RCP_DECL_HPP
44 
45 
51 #include "Teuchos_RCPNode.hpp"
52 #include "Teuchos_ENull.hpp"
53 #include "Teuchos_NullIteratorTraits.hpp"
54 
55 
56 #ifdef REFCOUNTPTR_INLINE_FUNCS
57 # define REFCOUNTPTR_INLINE inline
58 #else
59 # define REFCOUNTPTR_INLINE
60 #endif
61 
62 
63 #ifdef TEUCHOS_DEBUG
64 # define TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL
65 #endif
66 
67 
68 namespace Teuchos {
69 
70 
72 template<class T> class Ptr;
73 
74 
75 enum ERCPWeakNoDealloc { RCP_WEAK_NO_DEALLOC };
76 enum ERCPUndefinedWeakNoDealloc { RCP_UNDEFINED_WEAK_NO_DEALLOC };
77 enum ERCPUndefinedWithDealloc { RCP_UNDEFINED_WITH_DEALLOC };
78 
79 
428 template<class T>
429 class RCP {
430 public:
431 
433  typedef T element_type;
434 
437 
459  inline RCP(ENull null_arg = null);
460 
481  inline explicit RCP( T* p, bool has_ownership = true );
482 
502  template<class Dealloc_T>
503  inline RCP(T* p, Dealloc_T dealloc, bool has_ownership);
504 
522  inline RCP(const RCP<T>& r_ptr);
523 
531  inline RCP(RCP<T>&& r_ptr);
532 
546  template<class T2>
547  inline RCP(const RCP<T2>& r_ptr);
548 
560  inline ~RCP();
561 
581  inline RCP<T>& operator=(const RCP<T>& r_ptr);
582 
592  inline RCP<T>& operator=(RCP<T>&& r_ptr);
593 
606  inline RCP<T>& operator=(ENull);
607 
609  inline void swap(RCP<T> &r_ptr);
610 
612 
615 
617  inline bool is_null() const;
618 
625  inline T* operator->() const;
626 
633  inline T& operator*() const;
634 
639  inline T* get() const;
640 
645  inline T* getRawPtr() const;
646 
648  inline Ptr<T> ptr() const;
649 
651  inline Ptr<T> operator()() const;
652 
654  inline RCP<const T> getConst() const;
655 
657 
660 
670  inline ERCPStrength strength() const;
671 
681  inline bool is_valid_ptr() const;
682 
688  inline int strong_count() const;
689 
695  inline int weak_count() const;
696 
698  inline int total_count() const;
699 
718  inline void set_has_ownership();
719 
730  inline bool has_ownership() const;
731 
763  inline Ptr<T> release();
764 
781  inline RCP<T> create_weak() const;
782 
799  inline RCP<T> create_strong() const;
800 
801 #if defined(HAVE_TEUCHOSCORE_CXX11) && defined(HAVE_TEUCHOS_THREAD_SAFE)
802 
803  inline RCP<T> create_strong_thread_safe() const; // this format to be determined
804 #endif
805 
813  template<class T2>
814  inline bool shares_resource(const RCP<T2>& r_ptr) const;
815 
817 
820 
824  inline const RCP<T>& assert_not_null() const;
825 
835  inline const RCP<T>& assert_valid_ptr() const;
836 
838  inline const RCP<T>& debug_assert_not_null() const
839  {
840 #ifdef TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL
841  assert_not_null();
842 #endif
843  return *this;
844  }
845 
847  inline const RCP<T>& debug_assert_valid_ptr() const
848  {
849 #ifdef TEUCHOS_DEBUG
851 #endif
852  return *this;
853  }
854 
856 
859 
861  inline void reset();
862 
873  template<class T2>
874  inline void reset(T2* p, bool has_ownership = true);
875 
877  TEUCHOS_DEPRECATED inline int count() const;
878 
880 
881 private:
882 
883  // //////////////////////////////////////////////////////////////
884  // Private data members
885 
886  T *ptr_; // NULL if this pointer is null
887  RCPNodeHandle node_; // NULL if this pointer is null
888 
889 public: // Bad bad bad
890 
891  // These constructors are put here because we don't want to confuse users
892  // who would otherwise see them.
893 
905  inline explicit RCP(T* p, ERCPWeakNoDealloc);
906 
917  inline explicit RCP(T* p, ERCPUndefinedWeakNoDealloc);
918 
925  template<class Dealloc_T>
926  inline RCP(T* p, Dealloc_T dealloc, ERCPUndefinedWithDealloc,
927  bool has_ownership = true);
928 
929 #ifndef DOXYGEN_COMPILE
930 
931  // WARNING: A general user should *never* call these functions!
932  inline RCP(T* p, const RCPNodeHandle &node);
933  inline T* access_private_ptr() const; // Does not throw
934  inline RCPNodeHandle& nonconst_access_private_node(); // Does not thorw
935  inline const RCPNodeHandle& access_private_node() const; // Does not thorw
936 
937 #endif
938 
939 };
940 
943 struct RCPComp {
945  template<class T1, class T2> inline
946  bool operator() (const RCP<T1> p1, const RCP<T2> p2) const{
947  return p1.get() < p2.get();
948  }
949 };
950 
953 struct RCPConstComp {
955  template<class T1, class T2> inline
956  bool operator() (const RCP<const T1> p1, const RCP<const T2> p2) const{
957  return p1.get() < p2.get();
958  }
959 };
960 
961 
962 
963 // 2008/09/22: rabartl: NOTE: I removed the TypeNameTraits<RCP<T> >
964 // specialization since I want to be able to print the type name of an RCP
965 // that does not have the type T fully defined!
966 
967 
972 template<typename T>
974 public:
975  static RCP<T> getNull() { return null; }
976 };
977 
978 
983 template<class T>
985 {
986 public:
988  typedef T ptr_t;
990  void free( T* ptr ) {
991  (void) ptr; // silence "unused parameter" compiler warning
992  }
993 };
994 
995 
1001 template<class T>
1003 {
1004 public:
1006  typedef T ptr_t;
1008  void free( T* ptr ) { if(ptr) delete ptr; }
1009 };
1010 
1011 
1017 template<class T>
1019 {
1020 public:
1022  typedef T ptr_t;
1024  void free( T* ptr ) { if(ptr) delete [] ptr; }
1025 };
1026 
1027 
1040 template<class T, class DeleteFunctor>
1042 {
1043 public:
1044  DeallocFunctorDelete( DeleteFunctor deleteFunctor ) : deleteFunctor_(deleteFunctor) {}
1045  typedef T ptr_t;
1046  void free( T* ptr ) { if(ptr) deleteFunctor_(ptr); }
1047 private:
1048  DeleteFunctor deleteFunctor_;
1049  DeallocFunctorDelete(); // Not defined and not to be called!
1050 };
1051 
1052 
1057 template<class T, class DeleteFunctor>
1059 deallocFunctorDelete( DeleteFunctor deleteFunctor )
1060 {
1061  return DeallocFunctorDelete<T,DeleteFunctor>(deleteFunctor);
1062 }
1063 
1064 
1078 template<class T, class DeleteHandleFunctor>
1080 {
1081 public:
1082  DeallocFunctorHandleDelete( DeleteHandleFunctor deleteHandleFunctor )
1083  : deleteHandleFunctor_(deleteHandleFunctor) {}
1084  typedef T ptr_t;
1085  void free( T* ptr ) { if(ptr) { T **hdl = &ptr; deleteHandleFunctor_(hdl); } }
1086 private:
1087  DeleteHandleFunctor deleteHandleFunctor_;
1088  DeallocFunctorHandleDelete(); // Not defined and not to be called!
1089 };
1090 
1091 
1096 template<class T, class DeleteHandleFunctor>
1098 deallocFunctorHandleDelete( DeleteHandleFunctor deleteHandleFunctor )
1099 {
1100  return DeallocFunctorHandleDelete<T,DeleteHandleFunctor>(deleteHandleFunctor);
1101 }
1102 
1103 
1112 template<class T, class Embedded, class Dealloc>
1114 {
1115 public:
1116  typedef typename Dealloc::ptr_t ptr_t;
1118  const Embedded &embedded, EPrePostDestruction prePostDestroy,
1119  Dealloc dealloc
1120  ) : embedded_(embedded), prePostDestroy_(prePostDestroy), dealloc_(dealloc)
1121  {}
1122  void setObj( const Embedded &embedded ) { embedded_ = embedded; }
1123  const Embedded& getObj() const { return embedded_; }
1124  Embedded& getNonconstObj() { return embedded_; }
1125  void free( T* ptr )
1126  {
1127  if (prePostDestroy_ == PRE_DESTROY)
1128  embedded_ = Embedded();
1129  dealloc_.free(ptr);
1130  if (prePostDestroy_ == POST_DESTROY)
1131  embedded_ = Embedded();
1132  }
1133 private:
1134  Embedded embedded_;
1135  EPrePostDestruction prePostDestroy_;
1136  Dealloc dealloc_;
1137  EmbeddedObjDealloc(); // Not defined and not to be called!
1138 };
1139 
1140 
1145 template<class T, class Embedded >
1147 embeddedObjDeallocDelete(const Embedded &embedded, EPrePostDestruction prePostDestroy)
1148 {
1150  embedded, prePostDestroy,DeallocDelete<T>());
1151 }
1152 
1153 
1158 template<class T, class Embedded >
1160 embeddedObjDeallocArrayDelete(const Embedded &embedded, EPrePostDestruction prePostDestroy)
1161 {
1163  embedded, prePostDestroy,DeallocArrayDelete<T>());
1164 }
1165 
1166 
1189 template<class T> inline
1190 RCP<T> rcp(T* p, bool owns_mem = true);
1191 
1192 
1236 template<class T, class Dealloc_T> inline
1237 RCP<T> rcpWithDealloc(T* p, Dealloc_T dealloc, bool owns_mem=true);
1238 
1239 
1241 template<class T, class Dealloc_T> inline
1242 TEUCHOS_DEPRECATED RCP<T> rcp( T* p, Dealloc_T dealloc, bool owns_mem )
1243 {
1244  return rcpWithDealloc(p, dealloc, owns_mem);
1245 }
1246 
1247 
1259 template<class T, class Dealloc_T> inline
1260 RCP<T> rcpWithDeallocUndef(T* p, Dealloc_T dealloc, bool owns_mem=true);
1261 
1262 
1272 template<class T> inline
1273 RCP<T> rcpFromRef(T& r);
1274 
1275 
1285 template<class T> inline
1286 RCP<T> rcpFromUndefRef(T& r);
1287 
1288 
1299 template<class T, class Embedded> inline
1300 RCP<T>
1301 rcpWithEmbeddedObjPreDestroy( T* p, const Embedded &embedded, bool owns_mem = true );
1302 
1303 
1314 template<class T, class Embedded> inline
1315 RCP<T>
1316 rcpWithEmbeddedObjPostDestroy( T* p, const Embedded &embedded, bool owns_mem = true );
1317 
1318 
1330 template<class T, class Embedded> inline
1331 RCP<T>
1332 rcpWithEmbeddedObj( T* p, const Embedded &embedded, bool owns_mem = true );
1333 
1334 
1335 // 2007/10/25: rabartl: ToDo: put in versions of
1336 // rcpWithEmbedded[Pre,Post]DestoryWithDealloc(...) that also accept a general
1337 // deallocator!
1338 
1339 
1349 template<class T, class ParentT>
1350 RCP<T> rcpWithInvertedObjOwnership(const RCP<T> &child, const RCP<ParentT> &parent);
1351 
1352 
1366 template<class T>
1367 RCP<T> rcpCloneNode(const RCP<T> &p);
1368 
1369 
1374 template<class T> inline
1375 bool is_null( const RCP<T> &p );
1376 
1377 
1382 template<class T> inline
1383 bool nonnull( const RCP<T> &p );
1384 
1385 
1390 template<class T> inline
1391 bool operator==( const RCP<T> &p, ENull );
1392 
1393 
1398 template<class T> inline
1399 bool operator!=( const RCP<T> &p, ENull );
1400 
1401 
1407 template<class T1, class T2> inline
1408 bool operator==( const RCP<T1> &p1, const RCP<T2> &p2 );
1409 
1410 
1416 template<class T1, class T2> inline
1417 bool operator!=( const RCP<T1> &p1, const RCP<T2> &p2 );
1418 
1419 
1429 template<class T2, class T1> inline
1430 RCP<T2> rcp_implicit_cast(const RCP<T1>& p1);
1431 
1432 
1443 template<class T2, class T1> inline
1444 RCP<T2> rcp_static_cast(const RCP<T1>& p1);
1445 
1446 
1453 template<class T2, class T1> inline
1454 RCP<T2> rcp_const_cast(const RCP<T1>& p1);
1455 
1456 
1480 template<class T2, class T1> inline
1481 RCP<T2> rcp_dynamic_cast(
1482  const RCP<T1>& p1, bool throw_on_fail = false
1483  );
1484 
1485 
1544 template<class T1, class T2>
1545 void set_extra_data( const T1 &extra_data, const std::string& name,
1546  const Ptr<RCP<T2> > &p, EPrePostDestruction destroy_when = POST_DESTROY,
1547  bool force_unique = true);
1548 
1568 template<class T1, class T2>
1569 const T1& get_extra_data( const RCP<T2>& p, const std::string& name );
1570 
1571 
1591 template<class T1, class T2>
1592 T1& get_nonconst_extra_data( RCP<T2>& p, const std::string& name );
1593 
1594 
1619 template<class T1, class T2>
1620 Ptr<const T1> get_optional_extra_data( const RCP<T2>& p, const std::string& name );
1621 
1622 
1647 template<class T1, class T2>
1648 Ptr<T1> get_optional_nonconst_extra_data( RCP<T2>& p, const std::string& name );
1649 
1650 
1662 template<class Dealloc_T, class T>
1663 const Dealloc_T& get_dealloc( const RCP<T>& p );
1664 
1665 
1677 template<class Dealloc_T, class T>
1678 Dealloc_T& get_nonconst_dealloc( const RCP<T>& p );
1679 
1680 
1695 template<class Dealloc_T, class T>
1696 Ptr<const Dealloc_T> get_optional_dealloc( const RCP<T>& p );
1697 
1698 
1713 template<class Dealloc_T, class T>
1714 Ptr<Dealloc_T> get_optional_nonconst_dealloc( const RCP<T>& p );
1715 
1716 
1723 template<class TOrig, class Embedded, class T>
1724 const Embedded& getEmbeddedObj( const RCP<T>& p );
1725 
1726 
1733 template<class TOrig, class Embedded, class T>
1734 Embedded& getNonconstEmbeddedObj( const RCP<T>& p );
1735 
1736 
1743 template<class TOrig, class Embedded, class T>
1744 Ptr<const Embedded> getOptionalEmbeddedObj( const RCP<T>& p );
1745 
1746 
1753 template<class TOrig, class Embedded, class T>
1754 Ptr<Embedded> getOptionalNonconstEmbeddedObj( const RCP<T>& p );
1755 
1756 
1762 template<class ParentT, class T>
1763 RCP<ParentT> getInvertedObjOwnershipParent(const RCP<T> &invertedChild);
1764 
1765 
1773 template<class T>
1774 std::ostream& operator<<( std::ostream& out, const RCP<T>& p );
1775 
1776 
1777 } // end namespace Teuchos
1778 
1779 
1780 #endif // TEUCHOS_RCP_DECL_HPP
~RCP()
Removes a reference to a dynamically allocated object and possibly deletes the object if owned...
RCP< const T > getConst() const
Return an RCP&lt;const T&gt; version of *this.
RCP(ENull null_arg=null)
Initialize RCP&lt;T&gt; to NULL.
DeallocFunctorHandleDelete< T, DeleteHandleFunctor > deallocFunctorHandleDelete(DeleteHandleFunctor deleteHandleFunctor)
A simple function used to create a functor deallocator object.
void free(T *ptr)
Deallocates a pointer ptr using delete ptr (required).
bool operator()(const RCP< T1 > p1, const RCP< T2 > p2) const
const RCP< T > & debug_assert_not_null() const
Calls assert_not_null() in a debug build.
RCP< T > create_weak() const
Create a new weak RCP object from another (strong) RCP object.
T ptr_t
Gives the type (required)
bool operator()(const RCP< const T1 > p1, const RCP< const T2 > p2) const
bool has_ownership() const
Returns true if this has ownership of object pointed to by this-&gt;get() in order to delete it...
bool nonnull(const std::shared_ptr< T > &p)
Returns true if p.get()!=NULL.
Deallocator subclass that Allows any functor object (including a function pointer) to be used to free...
bool is_null(const std::shared_ptr< T > &p)
Returns true if p.get()==NULL.
void swap(RCP< T > &r_ptr)
Swap the contents with some other RCP object.
RCP< T > create_strong() const
Create a new strong RCP object from another (weak) RCP object.
T * get() const
Get the raw C++ pointer to the underlying object.
ENull
Used to initialize a RCP object to NULL using an implicit conversion!
ERCPStrength strength() const
Strength of the pointer.
A deallocator class that wraps a simple value object and delegates to another deallocator object...
T * operator->() const
Pointer (-&gt;) access to members of underlying object.
Struct for comparing two RCPs. Simply compares the raw pointers contained within the RCPs...
void free(T *ptr)
Deallocates a pointer ptr using delete ptr (required).
Struct for comparing two RCPs. Simply compares the raw pointers contained within the RCPs...
Policy class for deallocator that uses delete to delete a pointer which is used by RCP...
EmbeddedObjDealloc< T, Embedded, DeallocArrayDelete< T > > embeddedObjDeallocArrayDelete(const Embedded &embedded, EPrePostDestruction prePostDestroy)
Create a dealocator with an embedded object using delete [].
T * getRawPtr() const
Get the raw C++ pointer to the underlying object.
TEUCHOS_DEPRECATED int count() const
Returns strong_count() [deprecated].
Deallocator class that uses delete [] to delete memory allocated uisng new []
const RCP< T > & assert_valid_ptr() const
If the object pointer is non-null, assert that it is still valid.
TEUCHOS_DEPRECATED RCP< T > rcp(T *p, Dealloc_T dealloc, bool owns_mem)
Deprecated.
void set_has_ownership()
Give this and other RCP&lt;&gt; objects ownership of the referenced object this-&gt;get(). ...
void reset()
Reset to null.
const RCP< T > & debug_assert_valid_ptr() const
Calls assert_valid_ptr() in a debug build.
Ptr< T > ptr() const
Get a safer wrapper raw C++ pointer to the underlying object.
Ptr< T > operator()() const
Shorthand for ptr().
bool shares_resource(const RCP< T2 > &r_ptr) const
Returns true if the smart pointers share the same underlying reference-counted object.
T ptr_t
Gives the type (required)
T & operator*() const
Dereference the underlying object.
ERCPStrength
Used to specify if the pointer is weak or strong.
RCP< T > & operator=(const RCP< T > &r_ptr)
Copy the pointer to the referenced object and increment the reference count.
Base traits class for getting a properly initialized null pointer.
const RCP< T > & assert_not_null() const
Throws NullReferenceError if this-&gt;get()==NULL, otherwise returns reference to *this.
Ptr< T > release()
Release the ownership of the underlying dynamically allocated object.
T ptr_t
Gives the type (required)
EmbeddedObjDealloc< T, Embedded, DeallocDelete< T > > embeddedObjDeallocDelete(const Embedded &embedded, EPrePostDestruction prePostDestroy)
Create a dealocator with an embedded object using delete.
bool is_valid_ptr() const
Return if the underlying object pointer is still valid or not.
Handle class that manages the RCPNode&#39;s reference counting.
RCP< ParentT > getInvertedObjOwnershipParent(const RCP< T > &invertedChild)
Get the parent back from an inverted ownership RCP.
EPrePostDestruction
Used to specify a pre or post destruction of extra data.
Policy class for deallocator for non-owned RCPs.
Deallocator subclass that Allows any functor object (including a function pointer) to be used to free...
DeallocFunctorDelete< T, DeleteFunctor > deallocFunctorDelete(DeleteFunctor deleteFunctor)
A simple function used to create a functor deallocator object.
Smart reference counting pointer class for automatic garbage collection.
Reference-counted pointer node classes.
void free(T *ptr)
Deallocates a pointer ptr using delete [] ptr (required).
int strong_count() const
Return the number of active RCP&lt;&gt; objects that have a &quot;strong&quot; reference to the underlying reference-...
int weak_count() const
Return the number of active RCP&lt;&gt; objects that have a &quot;weak&quot; reference to the underlying reference-co...
int total_count() const
Total count (strong_count() + weak_count()).
Simple wrapper class for raw pointers to single objects where no persisting relationship exists...
bool is_null() const
Returns true if the underlying pointer is null.