Teuchos - Trilinos Tools Package  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"
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 
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  {
1104  if (prePostDestroy_ == PRE_DESTROY)
1105  embedded_ = Embedded();
1106  dealloc_.free(ptr);
1107  if (prePostDestroy_ == POST_DESTROY)
1108  embedded_ = Embedded();
1109  }
1110 private:
1111  Embedded embedded_;
1112  EPrePostDestruction prePostDestroy_;
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...
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).
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()).
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!
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...
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 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.
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)
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.
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.
The Teuchos namespace contains all of the classes, structs and enums used by Teuchos, as well as a number of utility routines.
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.
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.
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.
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).
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