#include <Teuchos_RCPDecl.hpp>
Public Types | |
typedef T | element_type |
| |
Public Member Functions | |
RCP (ENull null_arg=null) | |
Initialize RCP<T> to NULL. | |
RCP (T *p, bool has_ownership=false) | |
Construct from a raw pointer. | |
RCP (const RCP< T > &r_ptr) | |
Initialize from another RCP<T> object. | |
template<class T2 > | |
RCP (const RCP< T2 > &r_ptr) | |
Initialize from another RCP<T2> object (implicit conversion only). | |
~RCP () | |
Removes a reference to a dynamically allocated object and possibly deletes the object if owned. | |
RCP< T > & | operator= (const RCP< T > &r_ptr) |
Copy the pointer to the referenced object and increment the reference count. | |
T * | operator-> () const |
Pointer (-> ) access to members of underlying object. | |
T & | operator* () const |
Dereference the underlying object. | |
T * | get () const |
Get the raw C++ pointer to the underlying 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. | |
Ptr< T > | release () |
Release the ownership of the underlying dynamically allocated object. | |
int | count () const |
Return the number of RCP<> objects that have a reference to the underlying pointer that is being shared. | |
void | set_has_ownership () |
Give this and other RCP<> objects ownership of the referenced object this->get() . | |
bool | has_ownership () const |
Returns true if this has ownership of object pointed to by this->get() in order to delete it. | |
template<class T2 > | |
bool | shares_resource (const RCP< T2 > &r_ptr) const |
Returns true if the smart pointers share the same underlying reference-counted object. | |
const RCP< T > & | assert_not_null () const |
Throws NullReferenceError if this->get()==NULL , otherwise returns reference to *this . | |
template<class Dealloc_T > | |
REFCOUNTPTR_INLINE | RCP (T *p, Dealloc_T dealloc, bool has_ownership_in) |
template<class T> | |
RCP (T *p, RCPNode *node) | |
Related Functions | |
(Note that these are not member functions.) | |
enum | ENull { null } |
Used to initialize a RCP object to NULL using an implicit conversion! More... | |
template<class T > | |
RCP< T > | rcp (T *p, bool owns_mem=true) |
Create a RCP object properly typed. | |
template<class T , class Dealloc_T > | |
RCP< T > | rcp (T *p, Dealloc_T dealloc, bool owns_mem) |
Initialize from a raw pointer with a deallocation policy. | |
template<class T > | |
Teuchos::RCP< T > | rcpFromRef (T &r) |
Return a non-owning RCP object from a raw object reference. | |
template<class T > | |
bool | is_null (const RCP< T > &p) |
Returns true if p.get()==NULL . | |
template<class T > | |
bool | operator== (const RCP< T > &p, ENull) |
Returns true if p.get()==NULL . | |
template<class T > | |
bool | operator!= (const RCP< T > &p, ENull) |
Returns true if p.get()!=NULL . | |
template<class T1 , class T2 > | |
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. | |
template<class T1 , class T2 > | |
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 node. | |
template<class T2 , class T1 > | |
RCP< T2 > | rcp_implicit_cast (const RCP< T1 > &p1) |
Implicit cast of underlying RCP type from T1* to T2* . | |
template<class T2 , class T1 > | |
RCP< T2 > | rcp_static_cast (const RCP< T1 > &p1) |
Static cast of underlying RCP type from T1* to T2* . | |
template<class T2 , class T1 > | |
RCP< T2 > | rcp_const_cast (const RCP< T1 > &p1) |
Constant cast of underlying RCP type from T1* to T2* . | |
template<class T2 , class T1 > | |
RCP< T2 > | rcp_dynamic_cast (const RCP< T1 > &p1, bool throw_on_fail=false) |
Dynamic cast of underlying RCP type from T1* to T2* . | |
template<class T1 , class T2 > | |
void | set_extra_data (const T1 &extra_data, const std::string &name, RCP< T2 > *p, EPrePostDestruction destroy_when=POST_DESTROY, bool force_unique=true) |
Set extra data associated with a RCP object. | |
template<class T1 , class T2 > | |
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. | |
template<class T1 , class T2 > | |
T1 & | get_nonconst_extra_data (const RCP< T2 > &p, const std::string &name) |
Get a non-const reference to extra data associated with a RCP object. | |
template<class T1 , class T2 > | |
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. | |
template<class T1 , class T2 > | |
Ptr< T1 > | get_optional_nonconst_extra_data (const RCP< T2 > &p, const std::string &name) |
Get a pointer to non-const extra data (if it exists) associated with a RCP object. | |
template<class Dealloc_T , class T > | |
const Dealloc_T & | get_dealloc (const RCP< T > &p) |
Return a const reference to the underlying deallocator object. | |
template<class Dealloc_T , class T > | |
Dealloc_T & | get_nonconst_dealloc (const RCP< T > &p) |
Return a non-const reference to the underlying deallocator object. | |
template<class Dealloc_T , class T > | |
Ptr< const Dealloc_T > | get_optional_dealloc (const RCP< T > &p) |
Return a pointer to the underlying const deallocator object if it exists. | |
template<class Dealloc_T , class T > | |
Ptr< Dealloc_T > | get_optional_nonconst_dealloc (const RCP< T > &p) |
Return a pointer to the underlying non-const deallocator object if it exists. | |
template<class TOrig , class Embedded , class T > | |
const Embedded & | getEmbeddedObj (const RCP< T > &p) |
Get a const reference to an embedded object that was set by calling rcpWithEmbeddedObjPreDestroy() , rcpWithEmbeddedObjPostDestory() , or rcpWithEmbeddedObj() . | |
template<class TOrig , class Embedded , class T > | |
Embedded & | getNonconstEmbeddedObj (const RCP< T > &p) |
Get a const reference to an embedded object that was set by calling rcpWithEmbeddedObjPreDestroy() , rcpWithEmbeddedObjPostDestory() , or rcpWithEmbeddedObj() . | |
template<class T > | |
std::ostream & | operator<< (std::ostream &out, const RCP< T > &p) |
Output stream inserter. |
For a carefully written discussion about what this class is and basic details on how to use it see the beginners guide.
Quickstart for RCP
Here we present a short, but fairly comprehensive, quick-start for the use of RCP<>
. The use cases described here should cover the overwhelming majority of the use instances of RCP<>
in a typical program.
The following class hierarchy will be used in the C++ examples given below.
class A { public: virtual ~A(){} virtual void f(){} }; class B1 : virtual public A {}; class B2 : virtual public A {}; class C : virtual public B1, virtual public B2 {}; class D {}; class E : public D {};
All of the following code examples used in this quickstart are assumed to be in the namespace Teuchos
or have appropriate using Teuchos::...
declarations. This removes the need to explicitly use Teuchos::
to qualify classes, functions and other declarations from the Teuchos
namespace. Note that some of the runtime checks are denoted as "debug runtime checked" which means that checking will only be performed in a debug build (that is one where the macro TEUCHOS_REFCOUNTPTR_ASSERT_NONNULL, or TEUCHOS_DEBUG is defined at compile time).
RCP<>
objects
RCP<>
object using new
RCP<C> c_ptr = rcp(new C);
RCP<>
object to an array allocated using new[n]
: Teuchos::DeallocArrayDelete
RCP<C> c_ptr = rcp(new C[n],DeallocArrayDelete<C>(),true);
RCP<>
object equipped with a specialized deallocator function : Teuchos::DeallocFunctorDelete
void someDeallocFunction(C* c_ptr); RCP<C> c_ptr = rcp(new deallocFunctorDelete<C>(someDeallocFunction),true);
RCP<>
object to NULL
RCP<C> c_ptr;
RCP<C> c_ptr = null;
RCP<>
object to an object {not} allocated with new
C c; RCP<C> c_ptr = rcp(&c,false);
RCP<C> c_ptr = rcp(new C); // No cast RCP<A> a_ptr = c_ptr; // Cast to base class RCP<const A> ca_ptr = a_ptr; // Cast from non-const to const
RCP<C> c_ptr;
const RCP<C> c_ptr;
RCP<const C> c_ptr;
const RCP<const C> c_ptr;
RCP<>
objects (using assignment operator)
RCP<A> a_ptr; a_ptr = rcp(new C());
RCP<>
object
RCP<A> a_ptr1; RCP<A> a_ptr2 = rcp(new C()); a_ptr1 = a_ptr2; // Now a_ptr1 and a_ptr2 point to same C object
Teuchos::RCP::operator*()
C &c_ref = *c_ptr;
NULL
) : Teuchos::RCP::get()
C *c_rptr = c_ptr.get();
C *c_rptr = c_ptr.getRawPtr();
NULL
) : Teuchos::RCP::operator*()
C *c_rptr = &*c_ptr;
Teuchos::RCP::operator->()
c_ptr->f();
Teuchos::RCP::get()
, Teuchos::operator==()
, Teuchos::operator!=()
if( a_ptr.get() ) std::cout << "a_ptr is not null!\n";
or
if( a_ptr != null ) std::cout << "a_ptr is not null!\n";
or
if( !a_ptr.get() ) std::cout << "a_ptr is null!\n";
or
if( a_ptr == null ) std::cout << "a_ptr is null!\n";
or
if( is_null(a_ptr) ) std::cout << "a_ptr is null!\n";
RCP<C> c_ptr = rcp(new C); // No cast RCP<A> a_ptr = rcp_implicit_cast<A>(c_ptr); // To base RCP<const A> ca_ptr = rcp_implicit_cast<const A>(a_ptr);// To const
const
: rcp_const_cast()
RCP<const A> ca_ptr = rcp(new C); RCP<A> a_ptr = rcp_const_cast<A>(ca_ptr); // cast away const!
rcp_static_cast()
RCP<D> d_ptr = rcp(new E); RCP<E> e_ptr = rcp_static_cast<E>(d_ptr); // Unchecked, unsafe?
rcp_dynamic_cast()
RCP<A> a_ptr = rcp(new C); RCP<B1> b1_ptr = rcp_dynamic_cast<B1>(a_ptr); // Checked, safe! RCP<B2> b2_ptr = rcp_dynamic_cast<B2>(b1_ptr); // Checked, safe! RCP<C> c_ptr = rcp_dynamic_cast<C>(b2_ptr); // Checked, safe!
rcp_dynamic_cast()
RCP<A> a_ptr1 = rcp(new C); RCP<A> a_ptr2 = rcp(new A); RCP<B1> b1_ptr1 = rcp_dynamic_cast<B1>(a_ptr1,true); // Success! RCP<B1> b1_ptr2 = rcp_dynamic_cast<B1>(a_ptr2,true); // Throw std::bad_cast!
RCP<>
object with a custom deallocator : Teuchos::DeallocArrayDelete
RCP<C> c_ptr = rcp(new C[N],DeallocArrayDelete<C>(),true);
Teuchos::get_dealloc()
const DeallocArrayDelete<C>
&dealloc = get_dealloc<DeallocArrayDelete<C> >(c_ptr);
Teuchos::get_optional_dealloc()
const DeallocArrayDelete<C> *dealloc = get_optional_dealloc<DeallocArrayDelete<C> >(c_ptr); if(dealloc) std::cout << "This deallocator exits!\n";
Teuchos::set_extra_data()
set_extra_data(rcp(new B1),"A:B1",&a_ptr);
Teuchos::get_extra_data()
set_extra_data(rcp(new B1),"A:B1",&a_ptr,PRE_DESTORY);
Teuchos::get_extra_data()
get_extra_data<RCP<B1> >(a_ptr,"A:B1")->f();
Teuchos::get_extra_data()
get_extra_data<RCP<B1> >(a_ptr,"A:B1") = rcp(new C);
Teuchos::get_optional_extra_data()
const RCP<B1> *b1 = get_optional_extra_data<RCP<B1> >(a_ptr,"A:B1"); if(b1) (*b1)->f();
Type T
requirements:
Teuchos::TypeNameTraits<T>
specialization FancyOutputting_test.cpp, ParameterList/cxx_main.cpp, and TimeMonitor/cxx_main.cpp.
Definition at line 405 of file Teuchos_RCPDecl.hpp.
typedef T Teuchos::RCP< T >::element_type |
Teuchos::RCP< T >::RCP | ( | ENull | null_arg = null |
) | [inline] |
Initialize RCP<T>
to NULL.
This allows clients to write code like:
RCP<int> p = null;
RCP<int> p;
NULL
Definition at line 65 of file Teuchos_RCP.hpp.
Teuchos::RCP< T >::RCP | ( | T * | p, | |
bool | has_ownership = false | |||
) | [inline, explicit] |
Construct from a raw pointer.
Note that this constructor is declared explicit so there is no implicit conversion from a raw pointer to an RCP allowed. If has_ownership==false
, then no attempt to delete the object will occur.
Postconditons:
this->get() == p
this->count() == 1
this->has_ownership() == has_ownership
Definition at line 233 of file Teuchos_RCP.hpp.
REFCOUNTPTR_INLINE Teuchos::RCP< T >::RCP | ( | const RCP< T > & | r_ptr | ) | [inline] |
Initialize from another RCP<T>
object.
After construction, this
and r_ptr
will reference the same object.
This form of the copy constructor is required even though the below more general templated version is sufficient since some compilers will generate this function automatically which will give an incorrect implementation.
Postconditons:
this->get() == r_ptr.get()
this->count() == r_ptr.count()
this->has_ownership() == r_ptr.has_ownership()
r_ptr.get() != NULL
then r_ptr.count()
is incremented by 1 Definition at line 73 of file Teuchos_RCP.hpp.
REFCOUNTPTR_INLINE Teuchos::RCP< T >::RCP | ( | const RCP< T2 > & | r_ptr | ) | [inline] |
Initialize from another RCP<T2>
object (implicit conversion only).
This function allows the implicit conversion of smart pointer objects just like with raw C++ pointers. Note that this function will only compile if the statement T1 *ptr = r_ptr.get()
will compile.
Postconditons:
this->get() == r_ptr.get()
this->count() == r_ptr.count()
this->has_ownership() == r_ptr.has_ownership()
r_ptr.get() != NULL
then r_ptr.count()
is incremented by 1 Definition at line 83 of file Teuchos_RCP.hpp.
REFCOUNTPTR_INLINE Teuchos::RCP< T >::~RCP | ( | ) | [inline] |
Removes a reference to a dynamically allocated object and possibly deletes the object if owned.
Deletes the object if this->has_ownership() == true
and this->count() == 1
. If this->count() == 1
but this->has_ownership() == false
then the object is not deleted. If this->count() > 1
then the internal reference count shared by all the other related RCP<...>
objects for this shared object is deincremented by one. If this->get() == NULL
then nothing happens.
Definition at line 93 of file Teuchos_RCP.hpp.
REFCOUNTPTR_INLINE Teuchos::RCP< T >::RCP | ( | T * | p, | |
Dealloc_T | dealloc, | |||
bool | has_ownership_in | |||
) | [inline] |
Definition at line 254 of file Teuchos_RCP.hpp.
Definition at line 272 of file Teuchos_RCP.hpp.
const RCP< T > & Teuchos::RCP< T >::assert_not_null | ( | ) | const [inline] |
Throws NullReferenceError
if this->get()==NULL
, otherwise returns reference to *this
.
Definition at line 221 of file Teuchos_RCP.hpp.
REFCOUNTPTR_INLINE int Teuchos::RCP< T >::count | ( | ) | const [inline] |
Return the number of RCP<>
objects that have a reference to the underlying pointer that is being shared.
this->get() == NULL
then this function returns 0. Otherwise, this function returns 0
. Definition at line 181 of file Teuchos_RCP.hpp.
T * Teuchos::RCP< T >::get | ( | ) | const [inline] |
Get the raw C++ pointer to the underlying object.
NOTE: Prefer to get the safer Ptr<T> object from this->ptr()
!
Definition at line 148 of file Teuchos_RCP.hpp.
T * Teuchos::RCP< T >::getRawPtr | ( | ) | const [inline] |
Get the raw C++ pointer to the underlying object.
NOTE: Prefer to get the safer Ptr<T> object from this->ptr()
!
Definition at line 156 of file Teuchos_RCP.hpp.
REFCOUNTPTR_INLINE bool Teuchos::RCP< T >::has_ownership | ( | ) | const [inline] |
Returns true if this
has ownership of object pointed to by this->get()
in order to delete it.
See ~RCP() above.
== NULL
then this function always returns false
. Otherwise the value returned from this function depends on which function was called most recently, if any; set_has_ownership() (true
) or release() (false
). Definition at line 199 of file Teuchos_RCP.hpp.
T & Teuchos::RCP< T >::operator* | ( | ) | const [inline] |
Dereference the underlying object.
Preconditions:
this->get() != NULL
(throws NullReferenceError
) Definition at line 137 of file Teuchos_RCP.hpp.
T * Teuchos::RCP< T >::operator-> | ( | ) | const [inline] |
Pointer (->
) access to members of underlying object.
Preconditions:
this->get() != NULL
(throws NullReferenceError
) Definition at line 126 of file Teuchos_RCP.hpp.
REFCOUNTPTR_INLINE RCP< T > & Teuchos::RCP< T >::operator= | ( | const RCP< T > & | r_ptr | ) | [inline] |
Copy the pointer to the referenced object and increment the reference count.
If this->has_ownership() == true
and this->count() == 1
before this operation is called, then the object pointed to by this->get()
will be deleted (usually using delete
) prior to binding to the pointer (possibly NULL
) pointed to in r_ptr
. Assignment to self (i.e. this->get() == r_ptr.get()
) is harmless and this function does nothing.
Postconditons:
this->get() == r_ptr.get()
this->count() == r_ptr.count()
this->has_ownership() == r_ptr.has_ownership()
r_ptr.get() != NULL
then r_ptr.count()
is incremented by 1 Definition at line 107 of file Teuchos_RCP.hpp.
Ptr< T > Teuchos::RCP< T >::ptr | ( | ) | const [inline] |
Get a safer wrapper raw C++ pointer to the underlying object.
Definition at line 164 of file Teuchos_RCP.hpp.
REFCOUNTPTR_INLINE Ptr< T > Teuchos::RCP< T >::release | ( | ) | [inline] |
Release the ownership of the underlying dynamically allocated object.
WARNING! Never call delete rcp.release().get()
as this can cause all kinds of segfaults. Instead, release your use of the shared object by simply assigning the RCP
object to Teuchos::null
.
This function should only be used as last result when all hell has broken loose and memory management control has broken down. This function is not to be used lightly!
After this function is called then the client is responsible for deallocating the shared object no matter how many ref_count_prt<T>
objects have a reference to it. If this->
get()== NULL
, then this call is meaningless.
Note that this function does not have the exact same semantics as does auto_ptr<T>::release()
. In auto_ptr<T>::release()
, this
is set to NULL
while here in RCP<T>:: release() only an ownership flag is set and *this
still points to the same object. It would be difficult to duplicate the behavior of auto_ptr<T>::release()
for this class.
Postconditions:
this->has_ownership() == false
this->get()
Definition at line 172 of file Teuchos_RCP.hpp.
REFCOUNTPTR_INLINE void Teuchos::RCP< T >::set_has_ownership | ( | ) | [inline] |
Give this
and other RCP<>
objects ownership of the referenced object this->get()
.
See ~RCP() above. This function does nothing if this->get() == NULL
.
Postconditions:
this->get() == NULL
then this->has_ownership() == false
(always!). this->has_ownership() == true
Definition at line 191 of file Teuchos_RCP.hpp.
REFCOUNTPTR_INLINE bool Teuchos::RCP< T >::shares_resource | ( | const RCP< T2 > & | r_ptr | ) | const [inline] |
Returns true if the smart pointers share the same underlying reference-counted object.
This method does more than just check if this->get() == r_ptr.get()
. It also checks to see if the underlying reference counting machinary is the same.
Definition at line 210 of file Teuchos_RCP.hpp.
enum ENull [related] |
Used to initialize a RCP
object to NULL using an implicit conversion!
Definition at line 41 of file Teuchos_ENull.hpp.
const Dealloc_T & get_dealloc | ( | const RCP< T > & | p | ) | [related] |
Return a const
reference to the underlying deallocator object.
Preconditions:
p.get() != NULL
(throws NullReferenceError
) p
is same as Dealloc_T
(throws NullReferenceError
) const T1 & get_extra_data | ( | const RCP< T2 > & | p, | |
const std::string & | name | |||
) | [related] |
Get a const reference to extra data associated with a RCP
object.
p | [in] Smart pointer object that extra data is being extraced from. | |
name | [in] Name of the extra data. |
p.get() != NULL
(throws NullReferenceError
) name
and T1
must have been used in a previous call to set_extra_data()
(throws std::invalid_argument
). Note, this function must be a non-member function since the client must manually select the first template argument.
Dealloc_T & get_nonconst_dealloc | ( | const RCP< T > & | p | ) | [related] |
Return a non-const
reference to the underlying deallocator object.
Preconditions:
p.get() != NULL
(throws NullReferenceError
) p
is same as Dealloc_T
(throws NullReferenceError
) T1 & get_nonconst_extra_data | ( | const RCP< T2 > & | p, | |
const std::string & | name | |||
) | [related] |
Get a non-const reference to extra data associated with a RCP
object.
p | [in] Smart pointer object that extra data is being extraced from. | |
name | [in] Name of the extra data. |
p.get() != NULL
(throws NullReferenceError
) name
and T1
must have been used in a previous call to set_extra_data()
(throws std::invalid_argument
). Note, this function must be a non-member function since the client must manually select the first template argument.
Ptr< const Dealloc_T > get_optional_dealloc | ( | const RCP< T > & | p | ) | [related] |
Return a pointer to the underlying const
deallocator object if it exists.
Preconditions:
p.get() != NULL
(throws NullReferenceError
) Postconditions:
p
is same as Dealloc_T
then return!=NULL
, otherwise return==NULL
Ptr< const T1 > get_optional_extra_data | ( | const RCP< T2 > & | p, | |
const std::string & | name | |||
) | [related] |
Get a pointer to const extra data (if it exists) associated with a RCP
object.
p | [in] Smart pointer object that extra data is being extraced from. | |
name | [in] Name of the extra data. |
p.get() != NULL
(throws NullReferenceError
) Postconditions:
name
and T1
have been used in a previous call to set_extra_data()
then return !=NULL
and otherwise return == NULL
. Note, this function must be a non-member function since the client must manually select the first template argument.
Ptr< Dealloc_T > get_optional_nonconst_dealloc | ( | const RCP< T > & | p | ) | [related] |
Return a pointer to the underlying non-const
deallocator object if it exists.
Preconditions:
p.get() != NULL
(throws NullReferenceError
) Postconditions:
p
is same as Dealloc_T
then return!=NULL
, otherwise return==NULL
Ptr< T1 > get_optional_nonconst_extra_data | ( | const RCP< T2 > & | p, | |
const std::string & | name | |||
) | [related] |
Get a pointer to non-const extra data (if it exists) associated with a RCP
object.
p | [in] Smart pointer object that extra data is being extraced from. | |
name | [in] Name of the extra data. |
p.get() != NULL
(throws NullReferenceError
) Postconditions:
name
and T1
have been used in a previous call to set_extra_data()
then return !=NULL
and otherwise return == NULL
. Note, this function must be a non-member function since the client must manually select the first template argument.
const Embedded & getEmbeddedObj | ( | const RCP< T > & | p | ) | [related] |
Get a const reference to an embedded object that was set by calling rcpWithEmbeddedObjPreDestroy()
, rcpWithEmbeddedObjPostDestory()
, or rcpWithEmbeddedObj()
.
Embedded & getNonconstEmbeddedObj | ( | const RCP< T > & | p | ) | [related] |
Get a const reference to an embedded object that was set by calling rcpWithEmbeddedObjPreDestroy()
, rcpWithEmbeddedObjPostDestory()
, or rcpWithEmbeddedObj()
.
bool is_null | ( | const RCP< T > & | p | ) | [related] |
Returns true if p.get()==NULL
.
bool operator!= | ( | const RCP< T1 > & | p1, | |
const RCP< T2 > & | p2 | |||
) | [related] |
Return true if two RCP
objects do not point to the same referenced-counted object and have the same node.
Returns true if p.get()!=NULL
.
std::ostream & operator<< | ( | std::ostream & | out, | |
const RCP< T > & | p | |||
) | [related] |
Output stream inserter.
The implementation of this function just print pointer addresse<s and therefore puts not restrictions on the data types involved.
bool operator== | ( | const RCP< T1 > & | p1, | |
const RCP< T2 > & | p2 | |||
) | [related] |
Return true if two RCP
objects point to the same referenced-counted object and have the same node.
Returns true if p.get()==NULL
.
RCP< T > rcp | ( | T * | p, | |
Dealloc_T | dealloc, | |||
bool | owns_mem | |||
) | [related] |
Initialize from a raw pointer with a deallocation policy.
p | [in] Raw C++ pointer that this will represent. | |
dealloc | [in] Deallocator policy object (copied by value) that defines a function void Dealloc_T::free(T* p) that will free the underlying object. | |
owns_mem | [in] If true then return is allowed to delete the underlying pointer by calling dealloc.free(p) . when all references have been removed. |
void Dealloc_T::free(T* p)
exists. Postconditions:
return.get() == p
p == NULL
then return.count() == 0
return.has_ownership() == false
return.count() == 1
return.has_ownership() == owns_mem
By default, return
has ownership to delete the object pointed to by p
when return
is deleted (see ~RCP())
. If owns_mem==true
, it is vital that the address p
passed in is the same address that was returned by new
. With multiple inheritance this is not always the case. See the above discussion. This class is templated to accept a deallocator object that will free the pointer. The other functions use a default deallocator of type DeallocDelete
which has a method DeallocDelete::free()
which just calls delete p
.
RCP< T > rcp | ( | T * | p, | |
bool | owns_mem = true | |||
) | [related] |
Create a RCP
object properly typed.
p | [in] Pointer to an object to be reference counted. | |
owns_mem | [in] If owns_mem==true then delete p will be called when the last reference to this object is removed. If owns_mem==false then nothing will happen to delete the the object pointed to by p when the last reference is removed. |
owns_mem==true
then p
must have been created by calling new
to create the object since delete p
will be called eventually.
If the pointer p
did not come from new
then either the client should use the version of rcp()
that that uses a deallocator policy object or should pass in owns_mem = false
.
Constant cast of underlying RCP
type from T1*
to T2*
.
This function will compile only if (const_cast<T2*>(p1.get());
) compiles.
RCP< T2 > rcp_dynamic_cast | ( | const RCP< T1 > & | p1, | |
bool | throw_on_fail = false | |||
) | [related] |
Dynamic cast of underlying RCP
type from T1*
to T2*
.
p1 | [in] The smart pointer casting from | |
throw_on_fail | [in] If true then if the cast fails (for p1.get()!=NULL) then a |
If ( p1.get()!=NULL && throw_on_fail==true && dynamic_cast<T2*>(p1.get())==NULL ) == true
then an std::bad_cast
std::exception is thrown with a very informative error message.
If ( p1.get()!=NULL && dynamic_cast<T2*>(p1.get())!=NULL ) == true
then return.get() == dynamic_cast<T2*>(p1.get())
.
If ( p1.get()!=NULL && throw_on_fail==false && dynamic_cast<T2*>(p1.get())==NULL ) == true
then return.get() == NULL
.
If ( p1.get()==NULL ) == true
then return.get() == NULL
.
This function will compile only if (
dynamic_cast<T2*>(p1.get());
) compiles.
Static cast of underlying RCP
type from T1*
to T2*
.
The function will compile only if (static_cast<T2*>(p1.get());
) compiles.
This can safely be used for conversion down an inheritance hierarchy with polymorphic types only if dynamic_cast<T2>(p1.get()) == static_cast<T2>(p1.get())
. If not then you have to use rcp_dynamic_cast
<T2>(p1)
.
Teuchos::RCP< T > rcpFromRef | ( | T & | r | ) | [related] |
Return a non-owning RCP object from a raw object reference.
void set_extra_data | ( | const T1 & | extra_data, | |
const std::string & | name, | |||
RCP< T2 > * | p, | |||
EPrePostDestruction | destroy_when = POST_DESTROY , |
|||
bool | force_unique = true | |||
) | [related] |
Set extra data associated with a RCP
object.
extra_data | [in] Data object that will be set (copied) | |
name | [in] The name given to the extra data. The value of name together with the data type T1 of the extra data must be unique from any other such data or the other data will be overwritten. | |
p | [out] On output, will be updated with the input extra_data | |
destroy_when | [in] Determines when extra_data will be destroyed in relation to the underlying reference-counted object. If destroy_when==PRE_DESTROY then extra_data will be deleted before the underlying reference-counted object. If destroy_when==POST_DESTROY (the default) then extra_data will be deleted after the underlying reference-counted object. | |
force_unique | [in] Determines if this type and name pair must be unique in which case if an object with this same type and name already exists, then an std::exception will be thrown. The default is true for safety. |
T1
and same arguments p
and name
has already been made, then the current piece of extra data already set will be overwritten with extra_data
. However, if the type of the extra data T1
is different, then the extra data can be added and not overwrite existing extra data. This means that extra data is keyed on both the type and name. This helps to minimize the chance that clients will unexpectedly overwrite data by accident.
When the last RefcountPtr
object is removed and the reference-count node is deleted, then objects are deleted in the following order: (1) All of the extra data that where added with destroy_when==PRE_DESTROY
are first, (2) then the underlying reference-counted object is deleted, and (3) the rest of the extra data that was added with destroy_when==PRE_DESTROY
is then deleted. The order in which the objects are destroyed is not guaranteed. Therefore, clients should be careful not to add extra data that has deletion dependancies (instead consider using nested RCP objects as extra data which will guarantee the order of deletion).
Preconditions:
p->get() != NULL
(throws NullReferenceError
) T1
for extra_data
and the same std::string name
and force_unique==true
, then an std::invalid_argument
std::exception will be thrown.
Note, this function is made a non-member function to be consistent with the non-member get_extra_data()
functions.