Teuchos Package Browser (Single Doxygen Collection)  Version of the Day
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"
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 
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 
537  template<class T2>
538  inline RCP(const RCP<T2>& r_ptr);
539 
551  inline ~RCP();
552 
572  inline RCP<T>& operator=(const RCP<T>& r_ptr);
573 
586  inline RCP<T>& operator=(ENull);
587 
589  inline void swap(RCP<T> &r_ptr);
590 
592 
595 
597  inline bool is_null() const;
598 
605  inline T* operator->() const;
606 
613  inline T& operator*() const;
614 
619  inline T* get() const;
620 
625  inline T* getRawPtr() const;
626 
628  inline Ptr<T> ptr() const;
629 
631  inline Ptr<T> operator()() const;
632 
634  inline RCP<const T> getConst() const;
635 
637 
640 
652  inline ERCPStrength strength() const;
653 
663  inline bool is_valid_ptr() const;
664 
670  inline int strong_count() const;
671 
677  inline int weak_count() const;
678 
680  inline int total_count() const;
681 
700  inline void set_has_ownership();
701 
712  inline bool has_ownership() const;
713 
745  inline Ptr<T> release();
746 
763  inline RCP<T> create_weak() const;
764 
781  inline RCP<T> create_strong() const;
782 
790  template<class T2>
791  inline bool shares_resource(const RCP<T2>& r_ptr) const;
792 
794 
797 
801  inline const RCP<T>& assert_not_null() const;
802 
812  inline const RCP<T>& assert_valid_ptr() const;
813 
815  inline const RCP<T>& debug_assert_not_null() const
816  {
817 #ifdef TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL
818  assert_not_null();
819 #endif
820  return *this;
821  }
822 
824  inline const RCP<T>& debug_assert_valid_ptr() const
825  {
826 #ifdef TEUCHOS_DEBUG
828 #endif
829  return *this;
830  }
831 
833 
836 
838  inline void reset();
839 
850  template<class T2>
851  inline void reset(T2* p, bool has_ownership = true);
852 
854  TEUCHOS_DEPRECATED inline int count() const;
855 
857 
858 private:
859 
860  // //////////////////////////////////////////////////////////////
861  // Private data members
862 
863  T *ptr_; // NULL if this pointer is null
864  RCPNodeHandle node_; // NULL if this pointer is null
865 
866 public: // Bad bad bad
867 
868  // These constructors are put here because we don't want to confuse users
869  // who would otherwise see them.
870 
882  inline explicit RCP(T* p, ERCPWeakNoDealloc);
883 
894  inline explicit RCP(T* p, ERCPUndefinedWeakNoDealloc);
895 
902  template<class Dealloc_T>
903  inline RCP(T* p, Dealloc_T dealloc, ERCPUndefinedWithDealloc,
904  bool has_ownership = true);
905 
906 #ifndef DOXYGEN_COMPILE
907 
908  // WARNING: A general user should *never* call these functions!
909  inline RCP(T* p, const RCPNodeHandle &node);
910  inline T* access_private_ptr() const; // Does not throw
911  inline RCPNodeHandle& nonconst_access_private_node(); // Does not thorw
912  inline const RCPNodeHandle& access_private_node() const; // Does not thorw
913 
914 #endif
915 
916 };
917 
920 struct RCPComp {
922  template<class T1, class T2> inline
923  bool operator() (const RCP<T1> p1, const RCP<T2> p2) const{
924  return p1.get() < p2.get();
925  }
926 };
927 
930 struct RCPConstComp {
932  template<class T1, class T2> inline
933  bool operator() (const RCP<const T1> p1, const RCP<const T2> p2) const{
934  return p1.get() < p2.get();
935  }
936 };
937 
938 
939 
940 // 2008/09/22: rabartl: NOTE: I removed the TypeNameTraits<RCP<T> >
941 // specialization since I want to be able to print the type name of an RCP
942 // that does not have the type T fully defined!
943 
944 
949 template<typename T>
951 public:
952  static RCP<T> getNull() { return null; }
953 };
954 
955 
960 template<class T>
962 {
963 public:
965  typedef T ptr_t;
967  void free( T* ptr ) {
968  (void) ptr; // silence "unused parameter" compiler warning
969  }
970 };
971 
972 
978 template<class T>
980 {
981 public:
983  typedef T ptr_t;
985  void free( T* ptr ) { if(ptr) delete ptr; }
986 };
987 
988 
994 template<class T>
996 {
997 public:
999  typedef T ptr_t;
1001  void free( T* ptr ) { if(ptr) delete [] ptr; }
1002 };
1003 
1004 
1017 template<class T, class DeleteFunctor>
1019 {
1020 public:
1021  DeallocFunctorDelete( DeleteFunctor deleteFunctor ) : deleteFunctor_(deleteFunctor) {}
1022  typedef T ptr_t;
1023  void free( T* ptr ) { if(ptr) deleteFunctor_(ptr); }
1024 private:
1025  DeleteFunctor deleteFunctor_;
1026  DeallocFunctorDelete(); // Not defined and not to be called!
1027 };
1028 
1029 
1034 template<class T, class DeleteFunctor>
1036 deallocFunctorDelete( DeleteFunctor deleteFunctor )
1037 {
1038  return DeallocFunctorDelete<T,DeleteFunctor>(deleteFunctor);
1039 }
1040 
1041 
1055 template<class T, class DeleteHandleFunctor>
1057 {
1058 public:
1059  DeallocFunctorHandleDelete( DeleteHandleFunctor deleteHandleFunctor )
1060  : deleteHandleFunctor_(deleteHandleFunctor) {}
1061  typedef T ptr_t;
1062  void free( T* ptr ) { if(ptr) { T **hdl = &ptr; deleteHandleFunctor_(hdl); } }
1063 private:
1064  DeleteHandleFunctor deleteHandleFunctor_;
1065  DeallocFunctorHandleDelete(); // Not defined and not to be called!
1066 };
1067 
1068 
1073 template<class T, class DeleteHandleFunctor>
1075 deallocFunctorHandleDelete( DeleteHandleFunctor deleteHandleFunctor )
1076 {
1077  return DeallocFunctorHandleDelete<T,DeleteHandleFunctor>(deleteHandleFunctor);
1078 }
1079 
1080 
1089 template<class T, class Embedded, class Dealloc>
1091 {
1092 public:
1093  typedef typename Dealloc::ptr_t ptr_t;
1095  const Embedded &embedded, EPrePostDestruction prePostDestroy,
1096  Dealloc dealloc
1097  ) : embedded_(embedded), prePostDestroy_(prePostDestroy), dealloc_(dealloc)
1098  {}
1099  void setObj( const Embedded &embedded ) { embedded_ = embedded; }
1100  const Embedded& getObj() const { return embedded_; }
1101  Embedded& getNonconstObj() { return embedded_; }
1102  void free( T* ptr )
1103  {
1105  embedded_ = Embedded();
1106  dealloc_.free(ptr);
1108  embedded_ = Embedded();
1109  }
1110 private:
1111  Embedded embedded_;
1113  Dealloc dealloc_;
1114  EmbeddedObjDealloc(); // Not defined and not to be called!
1115 };
1116 
1117 
1122 template<class T, class Embedded >
1124 embeddedObjDeallocDelete(const Embedded &embedded, EPrePostDestruction prePostDestroy)
1125 {
1127  embedded, prePostDestroy,DeallocDelete<T>());
1128 }
1129 
1130 
1135 template<class T, class Embedded >
1137 embeddedObjDeallocArrayDelete(const Embedded &embedded, EPrePostDestruction prePostDestroy)
1138 {
1140  embedded, prePostDestroy,DeallocArrayDelete<T>());
1141 }
1142 
1143 
1166 template<class T> inline
1167 RCP<T> rcp(T* p, bool owns_mem = true);
1168 
1169 
1213 template<class T, class Dealloc_T> inline
1214 RCP<T> rcpWithDealloc(T* p, Dealloc_T dealloc, bool owns_mem=true);
1215 
1216 
1218 template<class T, class Dealloc_T> inline
1219 TEUCHOS_DEPRECATED RCP<T> rcp( T* p, Dealloc_T dealloc, bool owns_mem )
1220 {
1221  return rcpWithDealloc(p, dealloc, owns_mem);
1222 }
1223 
1224 
1236 template<class T, class Dealloc_T> inline
1237 RCP<T> rcpWithDeallocUndef(T* p, Dealloc_T dealloc, bool owns_mem=true);
1238 
1239 
1249 template<class T> inline
1250 RCP<T> rcpFromRef(T& r);
1251 
1252 
1262 template<class T> inline
1263 RCP<T> rcpFromUndefRef(T& r);
1264 
1265 
1276 template<class T, class Embedded> inline
1277 RCP<T>
1278 rcpWithEmbeddedObjPreDestroy( T* p, const Embedded &embedded, bool owns_mem = true );
1279 
1280 
1291 template<class T, class Embedded> inline
1292 RCP<T>
1293 rcpWithEmbeddedObjPostDestroy( T* p, const Embedded &embedded, bool owns_mem = true );
1294 
1295 
1307 template<class T, class Embedded> inline
1308 RCP<T>
1309 rcpWithEmbeddedObj( T* p, const Embedded &embedded, bool owns_mem = true );
1310 
1311 
1312 // 2007/10/25: rabartl: ToDo: put in versions of
1313 // rcpWithEmbedded[Pre,Post]DestoryWithDealloc(...) that also accept a general
1314 // deallocator!
1315 
1316 
1326 template<class T, class ParentT>
1327 RCP<T> rcpWithInvertedObjOwnership(const RCP<T> &child, const RCP<ParentT> &parent);
1328 
1329 
1343 template<class T>
1344 RCP<T> rcpCloneNode(const RCP<T> &p);
1345 
1346 
1351 template<class T> inline
1352 bool is_null( const RCP<T> &p );
1353 
1354 
1359 template<class T> inline
1360 bool nonnull( const RCP<T> &p );
1361 
1362 
1367 template<class T> inline
1368 bool operator==( const RCP<T> &p, ENull );
1369 
1370 
1375 template<class T> inline
1376 bool operator!=( const RCP<T> &p, ENull );
1377 
1378 
1384 template<class T1, class T2> inline
1385 bool operator==( const RCP<T1> &p1, const RCP<T2> &p2 );
1386 
1387 
1393 template<class T1, class T2> inline
1394 bool operator!=( const RCP<T1> &p1, const RCP<T2> &p2 );
1395 
1396 
1406 template<class T2, class T1> inline
1407 RCP<T2> rcp_implicit_cast(const RCP<T1>& p1);
1408 
1409 
1420 template<class T2, class T1> inline
1421 RCP<T2> rcp_static_cast(const RCP<T1>& p1);
1422 
1423 
1430 template<class T2, class T1> inline
1431 RCP<T2> rcp_const_cast(const RCP<T1>& p1);
1432 
1433 
1457 template<class T2, class T1> inline
1458 RCP<T2> rcp_dynamic_cast(
1459  const RCP<T1>& p1, bool throw_on_fail = false
1460  );
1461 
1462 
1521 template<class T1, class T2>
1522 void set_extra_data( const T1 &extra_data, const std::string& name,
1523  const Ptr<RCP<T2> > &p, EPrePostDestruction destroy_when = POST_DESTROY,
1524  bool force_unique = true);
1525 
1545 template<class T1, class T2>
1546 const T1& get_extra_data( const RCP<T2>& p, const std::string& name );
1547 
1548 
1568 template<class T1, class T2>
1569 T1& get_nonconst_extra_data( RCP<T2>& p, const std::string& name );
1570 
1571 
1596 template<class T1, class T2>
1597 Ptr<const T1> get_optional_extra_data( const RCP<T2>& p, const std::string& name );
1598 
1599 
1624 template<class T1, class T2>
1625 Ptr<T1> get_optional_nonconst_extra_data( RCP<T2>& p, const std::string& name );
1626 
1627 
1639 template<class Dealloc_T, class T>
1640 const Dealloc_T& get_dealloc( const RCP<T>& p );
1641 
1642 
1654 template<class Dealloc_T, class T>
1655 Dealloc_T& get_nonconst_dealloc( const RCP<T>& p );
1656 
1657 
1672 template<class Dealloc_T, class T>
1673 Ptr<const Dealloc_T> get_optional_dealloc( const RCP<T>& p );
1674 
1675 
1690 template<class Dealloc_T, class T>
1691 Ptr<Dealloc_T> get_optional_nonconst_dealloc( const RCP<T>& p );
1692 
1693 
1700 template<class TOrig, class Embedded, class T>
1701 const Embedded& getEmbeddedObj( const RCP<T>& p );
1702 
1703 
1710 template<class TOrig, class Embedded, class T>
1711 Embedded& getNonconstEmbeddedObj( const RCP<T>& p );
1712 
1713 
1720 template<class TOrig, class Embedded, class T>
1721 Ptr<const Embedded> getOptionalEmbeddedObj( const RCP<T>& p );
1722 
1723 
1730 template<class TOrig, class Embedded, class T>
1731 Ptr<Embedded> getOptionalNonconstEmbeddedObj( const RCP<T>& p );
1732 
1733 
1739 template<class ParentT, class T>
1740 RCP<ParentT> getInvertedObjOwnershipParent(const RCP<T> &invertedChild);
1741 
1742 
1750 template<class T>
1751 std::ostream& operator<<( std::ostream& out, const RCP<T>& p );
1752 
1753 
1754 } // end namespace Teuchos
1755 
1756 
1757 #endif // TEUCHOS_RCP_DECL_HPP
const RCP< T > & assert_valid_ptr() const
If the object pointer is non-null, assert that it is still valid.
~RCP()
Removes a reference to a dynamically allocated object and possibly deletes the object if owned...
ERCPStrength
Used to specify if the pointer is weak or strong.
RCP(ENull null_arg=null)
Initialize RCP<T> to NULL.
int strong_count() const
Return the number of active RCP<> objects that have a "strong" reference to the underlying reference-...
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).
EPrePostDestruction prePostDestroy_
T ptr_t
Gives the type (required)
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.
int total_count() const
Total count (strong_count() + weak_count()).
DeallocFunctorDelete(DeleteFunctor deleteFunctor)
const RCP< T > & debug_assert_not_null() const
Calls assert_not_null() in a debug build.
RCP< T > create_strong() const
Create a new strong RCP object from another (weak) RCP object.
TEUCHOS_DEPRECATED int count() const
Returns strong_count() [deprecated].
int weak_count() const
Return the number of active RCP<> objects that have a "weak" reference to the underlying reference-co...
void swap(RCP< T > &r_ptr)
Swap the contents with some other RCP object.
ERCPStrength strength() const
Strength of the pointer.
bool is_valid_ptr() const
Return if the underlying object pointer is still valid or not.
T & operator*() const
Dereference the underlying object.
ENull
Used to initialize a RCP object to NULL using an implicit conversion!
ERCPUndefinedWeakNoDealloc
A deallocator class that wraps a simple value object and delegates to another deallocator object...
bool operator()(const RCP< T1 > p1, const RCP< T2 > p2) const
T * get() const
Get the raw C++ pointer to the 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).
bool shares_resource(const RCP< T2 > &r_ptr) const
Returns true if the smart pointers share the same underlying reference-counted object.
bool is_null() const
Returns true if the underlying pointer is null.
Struct for comparing two RCPs. Simply compares the raw pointers contained within the RCPs...
bool operator!=(const Allocator< T > &a_t, const Allocator< U > &a_u)
Return ! (a_t == a_u) (see above).
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 * operator->() const
Pointer (->) access to members of underlying object.
const Embedded & getObj() const
const RCP< T > & debug_assert_valid_ptr() const
Calls assert_valid_ptr() in a debug build.
Deallocator class that uses delete [] to delete memory allocated uisng new []
TEUCHOS_DEPRECATED RCP< T > rcp(T *p, Dealloc_T dealloc, bool owns_mem)
Deprecated.
EmbeddedObjDealloc(const Embedded &embedded, EPrePostDestruction prePostDestroy, Dealloc dealloc)
void set_has_ownership()
Give this and other RCP<> objects ownership of the referenced object this->get(). ...
void reset()
Reset to null.
T ptr_t
Gives the type (required)
RCP< T > & operator=(const RCP< T > &r_ptr)
Copy the pointer to the referenced object and increment the reference count.
RCP< T > create_weak() const
Create a new weak RCP object from another (strong) RCP object.
Base traits class for getting a properly initialized null pointer.
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 operator==(const TwoDArray< T > &a1, const TwoDArray< T > &a2)
EPrePostDestruction
Used to specify a pre or post destruction of extra data.
bool has_ownership() const
Returns true if this has ownership of object pointed to by this->get() in order to delete it...
Handle class that manages the RCPNode&#39;s reference counting.
RCPNodeHandle node_
RCP< ParentT > getInvertedObjOwnershipParent(const RCP< T > &invertedChild)
Get the parent back from an inverted ownership RCP.
T * getRawPtr() const
Get the raw C++ pointer to the underlying object.
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.
Ptr< T > operator()() const
Shorthand for ptr().
const RCP< T > & assert_not_null() const
Throws NullReferenceError if this->get()==NULL, otherwise returns reference to *this.
void setObj(const Embedded &embedded)
RCP< const T > getConst() const
Return an RCP<const T> version of *this.
Reference-counted pointer node classes.
void free(T *ptr)
Deallocates a pointer ptr using delete [] ptr (required).
DeallocFunctorHandleDelete(DeleteHandleFunctor deleteHandleFunctor)
Ptr< T > ptr() const
Get a safer wrapper raw C++ pointer to the underlying object.
Simple wrapper class for raw pointers to single objects where no persisting relationship exists...
bool operator()(const RCP< const T1 > p1, const RCP< const T2 > p2) const