Teuchos - Trilinos Tools Package Version of the Day
Loading...
Searching...
No Matches
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
68namespace Teuchos {
69
70
72template<class T> class Ptr;
73
74
75enum ERCPWeakNoDealloc { RCP_WEAK_NO_DEALLOC };
76enum ERCPUndefinedWeakNoDealloc { RCP_UNDEFINED_WEAK_NO_DEALLOC };
77enum ERCPUndefinedWithDealloc { RCP_UNDEFINED_WITH_DEALLOC };
78
79
428template<class T>
429class RCP {
430public:
431
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
558 template<class T2>
559 inline RCP(const RCP<T2>& r_ptr, T* ptr);
560
572 inline ~RCP();
573
593 inline RCP<T>& operator=(const RCP<T>& r_ptr);
594
604 inline RCP<T>& operator=(RCP<T>&& r_ptr);
605
618 inline RCP<T>& operator=(ENull);
619
621 inline void swap(RCP<T> &r_ptr);
622
624
627
629 inline bool is_null() const;
630
637 inline T* operator->() const;
638
645 inline T& operator*() const;
646
651 inline T* get() const;
652
657 inline T* getRawPtr() const;
658
660 inline Ptr<T> ptr() const;
661
663 inline Ptr<T> operator()() const;
664
666 inline explicit operator bool() const;
667
669 inline RCP<const T> getConst() const;
670
672
675
685 inline ERCPStrength strength() const;
686
696 inline bool is_valid_ptr() const;
697
703 inline int strong_count() const;
704
710 inline int weak_count() const;
711
713 inline int total_count() const;
714
733 inline void set_has_ownership();
734
745 inline bool has_ownership() const;
746
778 inline Ptr<T> release();
779
796 inline RCP<T> create_weak() const;
797
814 inline RCP<T> create_strong() const;
815
816#if defined(HAVE_TEUCHOSCORE_CXX11) && defined(HAVE_TEUCHOS_THREAD_SAFE)
818 inline RCP<T> create_strong_thread_safe() const; // this format to be determined
819#endif
820
828 template<class T2>
829 inline bool shares_resource(const RCP<T2>& r_ptr) const;
830
832
835
839 inline const RCP<T>& assert_not_null() const;
840
850 inline const RCP<T>& assert_valid_ptr() const;
851
853 inline const RCP<T>& debug_assert_not_null() const
854 {
855#ifdef TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL
857#endif
858 return *this;
859 }
860
862 inline const RCP<T>& debug_assert_valid_ptr() const
863 {
864#ifdef TEUCHOS_DEBUG
866#endif
867 return *this;
868 }
869
871
874
876 inline void reset();
877
888 template<class T2>
889 inline void reset(T2* p, bool has_ownership = true);
890
892
893private:
894
895 // //////////////////////////////////////////////////////////////
896 // Private data members
897
898 T *ptr_; // NULL if this pointer is null
899 RCPNodeHandle node_; // NULL if this pointer is null
900
901public: // Bad bad bad
902
903 // These constructors are put here because we don't want to confuse users
904 // who would otherwise see them.
905
917 inline explicit RCP(T* p, ERCPWeakNoDealloc);
918
929 inline explicit RCP(T* p, ERCPUndefinedWeakNoDealloc);
930
937 template<class Dealloc_T>
938 inline RCP(T* p, Dealloc_T dealloc, ERCPUndefinedWithDealloc,
939 bool has_ownership = true);
940
941#ifndef DOXYGEN_COMPILE
942
943 // WARNING: A general user should *never* call these functions!
944 inline RCP(T* p, const RCPNodeHandle &node);
945 inline T* access_private_ptr() const; // Does not throw
946 inline RCPNodeHandle& nonconst_access_private_node(); // Does not thorw
947 inline const RCPNodeHandle& access_private_node() const; // Does not thorw
948
949#endif
950
951};
952
955struct RCPComp {
957 template<class T1, class T2> inline
958 bool operator() (const RCP<T1> p1, const RCP<T2> p2) const{
959 return p1.get() < p2.get();
960 }
961};
962
967 template<class T1, class T2> inline
968 bool operator() (const RCP<const T1> p1, const RCP<const T2> p2) const{
969 return p1.get() < p2.get();
970 }
971};
972
973
974
975// 2008/09/22: rabartl: NOTE: I removed the TypeNameTraits<RCP<T> >
976// specialization since I want to be able to print the type name of an RCP
977// that does not have the type T fully defined!
978
979
984template<typename T>
986public:
987 static RCP<T> getNull() { return null; }
988};
989
990
995template<class T>
997{
998public:
1000 typedef T ptr_t;
1002 void free( T* ptr ) {
1003 (void) ptr; // silence "unused parameter" compiler warning
1004 }
1005};
1006
1007
1013template<class T>
1015{
1016public:
1018 typedef T ptr_t;
1020 void free( T* ptr ) { if(ptr) delete ptr; }
1021};
1022
1023
1029template<class T>
1031{
1032public:
1034 typedef T ptr_t;
1036 void free( T* ptr ) { if(ptr) delete [] ptr; }
1037};
1038
1039
1052template<class T, class DeleteFunctor>
1054{
1055public:
1057 typedef T ptr_t;
1058 void free( T* ptr ) { if(ptr) deleteFunctor_(ptr); }
1059private:
1060 DeleteFunctor deleteFunctor_;
1061 DeallocFunctorDelete(); // Not defined and not to be called!
1062};
1063
1064
1069template<class T, class DeleteFunctor>
1075
1076
1090template<class T, class DeleteHandleFunctor>
1092{
1093public:
1095 : deleteHandleFunctor_(deleteHandleFunctor) {}
1096 typedef T ptr_t;
1097 void free( T* ptr ) { if(ptr) { T **hdl = &ptr; deleteHandleFunctor_(hdl); } }
1098private:
1099 DeleteHandleFunctor deleteHandleFunctor_;
1100 DeallocFunctorHandleDelete(); // Not defined and not to be called!
1101};
1102
1103
1108template<class T, class DeleteHandleFunctor>
1114
1115
1124template<class T, class Embedded, class Dealloc>
1126{
1127public:
1128 typedef typename Dealloc::ptr_t ptr_t;
1132 ) : embedded_(embedded), prePostDestroy_(prePostDestroy), dealloc_(dealloc)
1133 {}
1134 void setObj( const Embedded &embedded ) { embedded_ = embedded; }
1135 const Embedded& getObj() const { return embedded_; }
1136 Embedded& getNonconstObj() { return embedded_; }
1137 void free( T* ptr )
1138 {
1139 if (prePostDestroy_ == PRE_DESTROY)
1140 embedded_ = Embedded();
1141 dealloc_.free(ptr);
1142 if (prePostDestroy_ == POST_DESTROY)
1143 embedded_ = Embedded();
1144 }
1145private:
1146 Embedded embedded_;
1147 EPrePostDestruction prePostDestroy_;
1148 Dealloc dealloc_;
1149 EmbeddedObjDealloc(); // Not defined and not to be called!
1150};
1151
1152
1157template<class T, class Embedded >
1164
1165
1170template<class T, class Embedded >
1177
1178
1201template<class T> inline
1202RCP<T> rcp(T* p, bool owns_mem = true);
1203
1209template <typename T, typename ... Args>
1210inline auto make_rcp(Args&& ... args)
1211{
1212 return Teuchos::rcp(
1213 new T(std::forward<Args>(args)...)
1214 );
1215}
1216
1260template<class T, class Dealloc_T> inline
1262
1263
1265template<class T, class Dealloc_T> inline
1267{
1268 return rcpWithDealloc(p, dealloc, owns_mem);
1269}
1270
1271
1283template<class T, class Dealloc_T> inline
1285
1286
1296template<class T> inline
1298
1299
1309template<class T> inline
1311
1312
1323template<class T, class Embedded> inline
1324RCP<T>
1326
1327
1338template<class T, class Embedded> inline
1339RCP<T>
1341
1342
1354template<class T, class Embedded> inline
1355RCP<T>
1357
1358
1359// 2007/10/25: rabartl: ToDo: put in versions of
1360// rcpWithEmbedded[Pre,Post]DestoryWithDealloc(...) that also accept a general
1361// deallocator!
1362
1363
1373template<class T, class ParentT>
1375
1376
1390template<class T>
1392
1393
1398template<class T> inline
1399bool is_null( const RCP<T> &p );
1400
1401
1406template<class T> inline
1407bool nonnull( const RCP<T> &p );
1408
1409
1414template<class T> inline
1415bool operator==( const RCP<T> &p, ENull );
1416
1417
1422template<class T> inline
1423bool operator!=( const RCP<T> &p, ENull );
1424
1425
1431template<class T1, class T2> inline
1432bool operator==( const RCP<T1> &p1, const RCP<T2> &p2 );
1433
1434
1440template<class T1, class T2> inline
1441bool operator!=( const RCP<T1> &p1, const RCP<T2> &p2 );
1442
1443
1453template<class T2, class T1> inline
1455
1456
1467template<class T2, class T1> inline
1469
1470
1477template<class T2, class T1> inline
1479
1480
1504template<class T2, class T1> inline
1506 const RCP<T1>& p1, bool throw_on_fail = false
1507 );
1508
1509
1568template<class T1, class T2>
1569void set_extra_data( const T1 &extra_data, const std::string& name,
1570 const Ptr<RCP<T2> > &p, EPrePostDestruction destroy_when = POST_DESTROY,
1571 bool force_unique = true);
1572
1592template<class T1, class T2>
1593const T1& get_extra_data( const RCP<T2>& p, const std::string& name );
1594
1595
1615template<class T1, class T2>
1616T1& get_nonconst_extra_data( RCP<T2>& p, const std::string& name );
1617
1618
1643template<class T1, class T2>
1644Ptr<const T1> get_optional_extra_data( const RCP<T2>& p, const std::string& name );
1645
1646
1671template<class T1, class T2>
1673
1674
1686template<class Dealloc_T, class T>
1688
1689
1701template<class Dealloc_T, class T>
1703
1704
1719template<class Dealloc_T, class T>
1721
1722
1737template<class Dealloc_T, class T>
1739
1740
1747template<class TOrig, class Embedded, class T>
1749
1750
1757template<class TOrig, class Embedded, class T>
1759
1760
1767template<class TOrig, class Embedded, class T>
1769
1770
1777template<class TOrig, class Embedded, class T>
1779
1780
1786template<class ParentT, class T>
1788
1789
1797template<class T>
1798std::ostream& operator<<( std::ostream& out, const RCP<T>& p );
1799
1800
1801} // end namespace Teuchos
1802
1803
1804#endif // TEUCHOS_RCP_DECL_HPP
Reference-counted pointer node classes.
Deallocator class that uses delete [] to delete memory allocated uisng new []
T ptr_t
Gives the type (required)
void free(T *ptr)
Deallocates a pointer ptr using delete [] ptr (required).
Policy class for deallocator that uses delete to delete a pointer which is used by RCP.
T ptr_t
Gives the type (required)
void free(T *ptr)
Deallocates a pointer ptr using delete ptr (required).
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.
Deallocator subclass that Allows any functor object (including a function pointer) to be used to free...
DeallocFunctorHandleDelete< T, DeleteHandleFunctor > deallocFunctorHandleDelete(DeleteHandleFunctor deleteHandleFunctor)
A simple function used to create a functor deallocator object.
Policy class for deallocator for non-owned RCPs.
T ptr_t
Gives the type (required)
void free(T *ptr)
Deallocates a pointer ptr using delete ptr (required).
A deallocator class that wraps a simple value object and delegates to another deallocator object.
EmbeddedObjDealloc< T, Embedded, DeallocArrayDelete< T > > embeddedObjDeallocArrayDelete(const Embedded &embedded, EPrePostDestruction prePostDestroy)
Create a dealocator with an embedded object using delete [].
EmbeddedObjDealloc< T, Embedded, DeallocDelete< T > > embeddedObjDeallocDelete(const Embedded &embedded, EPrePostDestruction prePostDestroy)
Create a dealocator with an embedded object using delete.
Base traits class for getting a properly initialized null pointer.
Simple wrapper class for raw pointers to single objects where no persisting relationship exists.
Handle class that manages the RCPNode's reference counting.
Smart reference counting pointer class for automatic garbage collection.
RCP< const T > getConst() const
Return an RCP<const T> version of *this.
RCP< T > rcpWithEmbeddedObjPreDestroy(T *p, const Embedded &embedded, bool owns_mem=true)
Create an RCP with and also put in an embedded object.
RCP< T > create_weak() const
Create a new weak RCP object from another (strong) RCP object.
bool operator==(const RCP< T1 > &p1, const RCP< T2 > &p2)
Return true if two RCP objects point to the same referenced-counted object and have the same node.
RCP< T > rcpWithDealloc(T *p, Dealloc_T dealloc, bool owns_mem=true)
Initialize from a raw pointer with a deallocation policy.
bool is_null(const RCP< T > &p)
Returns true if p.get()==NULL.
RCP< T2 > rcp_dynamic_cast(const RCP< T1 > &p1, bool throw_on_fail=false)
Dynamic cast of underlying RCP type from T1* to T2*.
RCP< T > rcp(T *p, bool owns_mem=true)
Create a RCP object properly typed.
RCP< T2 > rcp_static_cast(const RCP< T1 > &p1)
Static cast of underlying RCP type from T1* to T2*.
Ptr< Embedded > getOptionalNonconstEmbeddedObj(const RCP< T > &p)
Get an optional Ptr to a non-const embedded object if it was set by calling rcpWithEmbeddedObjPreDest...
Ptr< T > release()
Release the ownership of the underlying dynamically allocated object.
void reset()
Reset to null.
void set_has_ownership()
Give this and other RCP<> objects ownership of the referenced object this->get().
~RCP()
Removes a reference to a dynamically allocated object and possibly deletes the object if owned.
const RCP< T > & assert_valid_ptr() const
If the object pointer is non-null, assert that it is still valid.
bool operator!=(const RCP< T > &p, ENull)
Returns true if p.get()!=NULL.
Ptr< Dealloc_T > get_optional_nonconst_dealloc(const RCP< T > &p)
Return a pointer to the underlying non-const deallocator object if it exists.
bool shares_resource(const RCP< T2 > &r_ptr) const
Returns true if the smart pointers share the same underlying reference-counted object.
RCP< T > rcpWithEmbeddedObj(T *p, const Embedded &embedded, bool owns_mem=true)
Create an RCP with and also put in an embedded object.
Embedded & getNonconstEmbeddedObj(const RCP< T > &p)
Get a non-const reference to an embedded object that was set by calling rcpWithEmbeddedObjPreDestroy(...
RCP< T2 > rcp_implicit_cast(const RCP< T1 > &p1)
Implicit cast of underlying RCP type from T1* to T2*.
const Dealloc_T & get_dealloc(const RCP< T > &p)
Return a const reference to the underlying deallocator object.
Dealloc_T & get_nonconst_dealloc(const RCP< T > &p)
Return a non-const reference to the underlying deallocator object.
void swap(RCP< T > &r_ptr)
Swap the contents with some other RCP object.
RCP< T2 > rcp_const_cast(const RCP< T1 > &p1)
Constant cast of underlying RCP type from T1* to T2*.
RCP< T > rcpWithDeallocUndef(T *p, Dealloc_T dealloc, bool owns_mem=true)
Initialize from a raw pointer with a deallocation policy for an undefined type.
RCP< T > rcpFromRef(T &r)
Return a non-owning weak RCP object from a raw object reference for a defined type.
RCP(ENull null_arg=null)
Initialize RCP<T> to NULL.
Ptr< T1 > get_optional_nonconst_extra_data(RCP< T2 > &p, const std::string &name)
Get a pointer to non-const extra data (if it exists) associated with a RCP object.
bool is_null() const
Returns true if the underlying pointer is null.
RCP< T > rcpFromUndefRef(T &r)
Return a non-owning weak RCP object from a raw object reference for an undefined type.
RCP< T > rcpWithEmbeddedObjPostDestroy(T *p, const Embedded &embedded, bool owns_mem=true)
Create an RCP with and also put in an embedded object.
T * getRawPtr() const
Get the raw C++ pointer to the underlying object.
Ptr< T > ptr() const
Get a safer wrapper raw C++ pointer to the underlying object.
T1 & get_nonconst_extra_data(RCP< T2 > &p, const std::string &name)
Get a non-const reference to extra data associated with a RCP object.
const RCP< T > & assert_not_null() const
Throws NullReferenceError if this->get()==NULL, otherwise returns reference to *this.
const RCP< T > & debug_assert_valid_ptr() const
Calls assert_valid_ptr() in a debug build.
std::ostream & operator<<(std::ostream &out, const RCP< T > &p)
Output stream inserter.
Ptr< const T1 > get_optional_extra_data(const RCP< T2 > &p, const std::string &name)
Get a pointer to const extra data (if it exists) associated with a RCP object.
T * operator->() const
Pointer (->) access to members of underlying object.
bool is_valid_ptr() const
Return if the underlying object pointer is still valid or not.
const T1 & get_extra_data(const RCP< T2 > &p, const std::string &name)
Get a const reference to extra data associated with a RCP object.
RCP< T > create_strong() const
Create a new strong RCP object from another (weak) RCP object.
RCP< T > rcpWithInvertedObjOwnership(const RCP< T > &child, const RCP< ParentT > &parent)
Create a new RCP that inverts the ownership of parent and child.
Ptr< const Dealloc_T > get_optional_dealloc(const RCP< T > &p)
Return a pointer to the underlying const deallocator object if it exists.
bool has_ownership() const
Returns true if this has ownership of object pointed to by this->get() in order to delete it.
bool operator!=(const RCP< T1 > &p1, const RCP< T2 > &p2)
Return true if two RCP objects do not point to the same referenced-counted object and have the same n...
bool nonnull(const RCP< T > &p)
Returns true if p.get()!=NULL.
T * get() const
Get the raw C++ pointer to the underlying object.
ERCPStrength strength() const
Strength of the pointer.
void set_extra_data(const T1 &extra_data, const std::string &name, const Ptr< RCP< T2 > > &p, EPrePostDestruction destroy_when=POST_DESTROY, bool force_unique=true)
Set extra data associated with a RCP object.
RCP< T > rcpCloneNode(const RCP< T > &p)
Allocate a new RCP object with a new RCPNode with memory pointing to the initial node.
Ptr< const Embedded > getOptionalEmbeddedObj(const RCP< T > &p)
Get an optional Ptr to a const embedded object if it was set by calling rcpWithEmbeddedObjPreDestroy(...
int weak_count() const
Return the number of active RCP<> objects that have a "weak" reference to the underlying reference-co...
ENull
Used to initialize a RCP object to NULL using an implicit conversion!
const RCP< T > & debug_assert_not_null() const
Calls assert_not_null() in a debug build.
RCP< T > & operator=(const RCP< T > &r_ptr)
Copy the pointer to the referenced object and increment the reference count.
int total_count() const
Total count (strong_count() + weak_count()).
bool operator==(const RCP< T > &p, ENull)
Returns true if p.get()==NULL.
int strong_count() const
Return the number of active RCP<> objects that have a "strong" reference to the underlying reference-...
const Embedded & getEmbeddedObj(const RCP< T > &p)
Get a const reference to an embedded object that was set by calling rcpWithEmbeddedObjPreDestroy(),...
Ptr< T > operator()() const
Shorthand for ptr().
T & operator*() const
Dereference the underlying object.
ERCPStrength
Used to specify if the pointer is weak or strong.
EPrePostDestruction
Used to specify a pre or post destruction of extra data.
The Teuchos namespace contains all of the classes, structs and enums used by Teuchos,...
TEUCHOS_DEPRECATED RCP< T > rcp(T *p, Dealloc_T dealloc, bool owns_mem)
Deprecated.
auto make_rcp(Args &&... args)
RCP< ParentT > getInvertedObjOwnershipParent(const RCP< T > &invertedChild)
Get the parent back from an inverted ownership RCP.
Struct for comparing two RCPs. Simply compares the raw pointers contained within the RCPs.
bool operator()(const RCP< T1 > p1, const RCP< T2 > p2) const
Struct for comparing two RCPs. Simply compares the raw pointers contained within the RCPs.
bool operator()(const RCP< const T1 > p1, const RCP< const T2 > p2) const