Teuchos::RCP< T > Class Template Reference
[Teuchos Memory Management Utilities]

Smart reference counting pointer class for automatic garbage collection. More...

#include <Teuchos_RCPDecl.hpp>

List of all members.

Public Types

typedef T element_type
 

Public Member Functions

template<class T>
 RCP (T *p, const RCPNodeHandle &node)
Constructors/destructors/initializers.
 RCP (ENull null_arg=null)
 Initialize RCP<T> to NULL.
 RCP (T *p, ENull null_arg)
 Construct from a raw pointer without ownership statically.
 RCP (T *p, bool has_ownership=true)
 Construct from a raw pointer.
template<class Dealloc_T>
 RCP (T *p, Dealloc_T dealloc, bool has_ownership)
 Construct from a raw pointer and a custom deallocator. occur.
 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.
template<class T2>
void reset (T2 *p, bool has_ownership=true)
 Reset the raw pointer with default ownership to delete.
Object/Pointer Access Functions
bool is_null () const
 Returns true if the underlying pointer is null.
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.
Reference counting
ERCPStrength strength () const
 Strength of the pointer.
bool is_valid_ptr () const
 Return if the underlying object pointer is still valid or not.
int strong_count () const
 Return the number of active RCP<> objects that have a "strong" reference to the underlying reference-counted object.
int weak_count () const
 Return the number of active RCP<> objects that have a "weak" reference to the underlying reference-counted object.
int total_count () const
 Total count (strong_count() + weak_count()).
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.
Ptr< T > release ()
 Release the ownership of the underlying dynamically allocated object.
RCP< T > create_weak () const
 Create a new weak RCP object from another (strong) RCP object.
RCP< T > create_strong () const
 Create a new strong RCP object from another (weak) RCP object.
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.
Assertions
const RCP< T > & assert_not_null () const
 Throws NullReferenceError if this->get()==NULL, otherwise returns reference to *this.
const RCP< T > & assert_valid_ptr () const
 If the object pointer is non-null, assert that it is still valid.
Deprecated
int count () const
 Returns strong_count() [deprecated].

Related Functions

(Note that these are not member functions.)

enum  ENull
 Used to initialize a RCP object to NULL using an implicit conversion! More...
RCP< T > rcpFromPtr (const Ptr< T > &ptr)
 Create an RCP<T> from a Ptr<T> object.
RCP< T > rcp (T *p, bool owns_mem=true)
 Create a RCP object properly typed.
RCP< T > rcp (T *p, Dealloc_T dealloc, bool owns_mem)
 Initialize from a raw pointer with a deallocation policy.
Teuchos::RCP< T > rcpFromRef (T &r)
 Return a non-owning RCP object from a raw object reference.
bool is_null (const RCP< T > &p)
 Returns true if p.get()==NULL.
bool nonnull (const RCP< T > &p)
 Returns true if p.get()!=NULL.
bool operator== (const RCP< T > &p, ENull)
 Returns true if p.get()==NULL.
bool operator!= (const RCP< T > &p, ENull)
 Returns true if p.get()!=NULL.
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.
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.
RCP< T2 > rcp_implicit_cast (const RCP< T1 > &p1)
 Implicit cast of underlying RCP type from T1* to T2*.
RCP< T2 > rcp_static_cast (const RCP< T1 > &p1)
 Static cast of underlying RCP type from T1* to T2*.
RCP< T2 > rcp_const_cast (const RCP< T1 > &p1)
 Constant cast of underlying RCP type from T1* to T2*.
RCP< T2 > rcp_dynamic_cast (const RCP< T1 > &p1, bool throw_on_fail=false)
 Dynamic cast of underlying RCP type from T1* to T2*.
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.
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.
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.
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.
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.
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.
Ptr< const Dealloc_T > get_optional_dealloc (const RCP< T > &p)
 Return a pointer to the underlying const deallocator object if it exists.
Ptr< Dealloc_T > get_optional_nonconst_dealloc (const RCP< T > &p)
 Return a pointer to the underlying non-const deallocator object if it exists.
const Embedded & getEmbeddedObj (const RCP< T > &p)
 Get a const reference to an embedded object that was set by calling rcpWithEmbeddedObjPreDestroy(), rcpWithEmbeddedObjPostDestory(), or rcpWithEmbeddedObj().
Embedded & getNonconstEmbeddedObj (const RCP< T > &p)
 Get a non-const reference to an embedded object that was set by calling rcpWithEmbeddedObjPreDestroy(), rcpWithEmbeddedObjPostDestory(), or rcpWithEmbeddedObj().
Ptr< const Embedded > getOptionalEmbeddedObj (const RCP< T > &p)
 Get an optional Ptr to a const embedded object if it was set by calling rcpWithEmbeddedObjPreDestroy(), rcpWithEmbeddedObjPostDestory(), or rcpWithEmbeddedObj().
Ptr< Embedded > getOptionalNonconstEmbeddedObj (const RCP< T > &p)
 Get an optional Ptr to a non-const embedded object if it was set by calling rcpWithEmbeddedObjPreDestroy(), rcpWithEmbeddedObjPostDestory(), or rcpWithEmbeddedObj().
std::ostream & operator<< (std::ostream &out, const RCP< T > &p)
 Output stream inserter.


Detailed Description

template<class T>
class Teuchos::RCP< T >

Smart reference counting pointer class for automatic garbage collection.

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_DEBUG is defined at compile time).

  1. Creation of RCP<> objects

    1. Creating an RCP<> object using new

      RCP<C> c_ptr = rcp(new C);
      

    2. Creating a 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);
      

    3. Initializing a RCP<> object to NULL

      RCP<C> c_ptr;
      

      or

      RCP<C> c_ptr = null;
      

    4. Initializing a RCP<> object to an object {not} allocated with new

      C c;
      RCP<C> c_ptr = rcpFromRef(c);
      

    5. Copy constructor (implicit casting)

      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
      

    6. Representing constantness and non-constantness

      1. Non-constant pointer to non-constant object
        RCP<C> c_ptr;
        

      2. Constant pointer to non-constant object
        const RCP<C> c_ptr;
        

      3. Non-Constant pointer to constant object
        RCP<const C> c_ptr;
        

      4. Constant pointer to constant object
        const RCP<const C> c_ptr;
        

  2. Reinitialization of RCP<> objects (using assignment operator)

    1. Resetting from a raw pointer

      RCP<A> a_ptr;
      a_ptr = rcp(new C());
      

    2. Resetting to null

      RCP<A> a_ptr = rcp(new C());
      a_ptr = null; // The C object will be deleted here
      

    3. Assigning from a 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
      

  3. Accessing the reference-counted object

    1. Access to object reference (debug runtime checked) : Teuchos::RCP::operator*()

      C &c_ref = *c_ptr;
      

    2. Access to object pointer (unchecked, may return NULL) : Teuchos::RCP::get()

      C *c_rptr = c_ptr.get();
      

      or

      C *c_rptr = c_ptr.getRawPtr();
      

      WARNING:: Avoid exposing raw C++ pointers!

    3. Access to object pointer (debug runtime checked, will not return NULL) : Teuchos::RCP::operator*()

      C *c_rptr = &*c_ptr;
      

      WARNING:: Avoid exposing raw C++ pointers!

    4. Access of object's member (debug runtime checked) : Teuchos::RCP::operator->()

      c_ptr->f();
      

    5. Testing for non-null : Teuchos::RCP::get(), Teuchos::operator==(), Teuchos::operator!=()

      if (a_ptr.is_null) std::cout << "a_ptr is not null!\n";
      

      or

      if (a_ptr != null) std::cout << "a_ptr is not null!\n";
      

      or

    6. Testing for null

      if (!a_ptr.is_null()) 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";
      

  4. Casting

    1. Implicit casting (see copy constructor above)

      1. Using copy constructor (see above)

      2. Using conversion function

        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
        

    2. Casting away 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!
      

    3. Static cast (no runtime check) : rcp_static_cast()

      RCP<D>     d_ptr = rcp(new E);
      RCP<E>     e_ptr = rcp_static_cast<E>(d_ptr); // Unchecked, unsafe?
      

    4. Dynamic cast (runtime checked, failed cast allowed) : 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!
      

    5. Dynamic cast (runtime checked, failed cast not allowed) : 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!
      

  5. Customized deallocators

    1. Creating a RCP<> object with a custom deallocator : rcp()

      TODO: Update this example!

    2. Access customized deallocator (runtime checked, throws on failure) : Teuchos::get_dealloc()

      const MyCustomDealloc<C>
        &dealloc = get_dealloc<MyCustomDealloc<C> >(c_ptr);
      

    3. Access optional customized deallocator : Teuchos::get_optional_dealloc()

      const Ptr<const MyCustomDealloc<C> > dealloc =
        get_optional_dealloc<MyCustomDealloc<C> >(c_ptr);
      if (!is_null(dealloc))
        std::cout << "This deallocator exits!\n";
      

  6. Managing extra data

    1. Adding extra data (post destruction of extra data) : Teuchos::set_extra_data()

      set_extra_data(rcp(new B1), "A:B1", inOutArg(a_ptr));
      

    2. Adding extra data (pre destruction of extra data) : Teuchos::get_extra_data()

      set_extra_data(rcp(new B1),"A:B1", inOutArg(a_ptr), PRE_DESTORY);
      

    3. Retrieving extra data : Teuchos::get_extra_data()

      get_extra_data<RCP<B1> >(a_ptr, "A:B1")->f();
      

    4. Resetting extra data : Teuchos::get_extra_data()

      get_extra_data<RCP<B1> >(a_ptr, "A:B1") = rcp(new C);
      

    5. Retrieving optional extra data : Teuchos::get_optional_extra_data()

      const Ptr<const RCP<B1> > b1 =
        get_optional_extra_data<RCP<B1> >(a_ptr, "A:B1");
      if (!is_null(b1))
        (*b1)->f();
      

Examples:

FancyOutputting_test.cpp, ParameterList/cxx_main.cpp, and TimeMonitor/cxx_main.cpp.

Definition at line 410 of file Teuchos_RCPDecl.hpp.


Member Typedef Documentation

template<class T>
typedef T Teuchos::RCP< T >::element_type

Definition at line 414 of file Teuchos_RCPDecl.hpp.


Constructor & Destructor Documentation

template<class T>
Teuchos::RCP< T >::RCP ( ENull  null_arg = null  )  [inline]

Initialize RCP<T> to NULL.

Postconditons:

This allows clients to write code like:

   RCP<int> p = null;
or
   RCP<int> p;
and construct to NULL

Definition at line 62 of file Teuchos_RCP.hpp.

template<class T>
Teuchos::RCP< T >::RCP ( T *  p,
ENull  null_arg 
) [inline, explicit]

Construct from a raw pointer without ownership statically.

Postconditons:

NOTE: It is recommended that this constructor never be called directly but only through a type-specific non-member constructor function or at least through the general non-member rcp() function.

Definition at line 69 of file Teuchos_RCP.hpp.

template<class T>
Teuchos::RCP< T >::RCP ( T *  p,
bool  has_ownership = true 
) [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:

NOTE: It is recommended that this constructor never be called directly but only through a type-specific non-member constructor function or at least through the general non-member rcp() function.

Definition at line 89 of file Teuchos_RCP.hpp.

template<class T>
template<class Dealloc_T>
REFCOUNTPTR_INLINE Teuchos::RCP< T >::RCP ( T *  p,
Dealloc_T  dealloc,
bool  has_ownership 
)

Construct from a raw pointer and a custom deallocator. occur.

Parameters:
p [in] Pointer to the reference-counted object to be wrapped
dealloc [in] Deallocator policy object that will be copied by value and will perform the custom deallocation of the object pointed to by p when the last RCP object goes away. See the class DeallocDelete for the specfication and behavior of this policy interface.
Postconditons:

Definition at line 110 of file Teuchos_RCP.hpp.

template<class T>
REFCOUNTPTR_INLINE Teuchos::RCP< T >::RCP ( const RCP< T > &  r_ptr  ) 

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:

Definition at line 130 of file Teuchos_RCP.hpp.

template<class T>
template<class T2>
REFCOUNTPTR_INLINE Teuchos::RCP< T >::RCP ( const RCP< T2 > &  r_ptr  ) 

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:

Definition at line 138 of file Teuchos_RCP.hpp.

template<class T>
REFCOUNTPTR_INLINE Teuchos::RCP< T >::~RCP (  ) 

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->strong_count() == 1. If this->strong_count() == 1 but this->has_ownership() == false then the object is not deleted. If this->strong_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 146 of file Teuchos_RCP.hpp.


Member Function Documentation

template<class T>
REFCOUNTPTR_INLINE RCP< T > & Teuchos::RCP< T >::operator= ( const RCP< T > &  r_ptr  ) 

Copy the pointer to the referenced object and increment the reference count.

If this->has_ownership() == true and this->strong_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:

Provides the "strong guarantee" in a debug build!

Definition at line 152 of file Teuchos_RCP.hpp.

template<class T>
template<class T2>
REFCOUNTPTR_INLINE void Teuchos::RCP< T >::reset ( T2 *  p,
bool  has_ownership = true 
)

Reset the raw pointer with default ownership to delete.

Equivalent to calling:

     r_rcp = rcp(p)

Definition at line 167 of file Teuchos_RCP.hpp.

template<class T>
bool Teuchos::RCP< T >::is_null (  )  const [inline]

Returns true if the underlying pointer is null.

Definition at line 178 of file Teuchos_RCP.hpp.

template<class T>
T * Teuchos::RCP< T >::operator-> (  )  const [inline]

Pointer (->) access to members of underlying object.

Preconditions:

Definition at line 186 of file Teuchos_RCP.hpp.

template<class T>
T & Teuchos::RCP< T >::operator * (  )  const [inline]

Dereference the underlying object.

Preconditions:

Definition at line 196 of file Teuchos_RCP.hpp.

template<class T>
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 205 of file Teuchos_RCP.hpp.

template<class T>
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 214 of file Teuchos_RCP.hpp.

template<class T>
Ptr< T > Teuchos::RCP< T >::ptr (  )  const [inline]

Get a safer wrapper raw C++ pointer to the underlying object.

Definition at line 222 of file Teuchos_RCP.hpp.

template<class T>
ERCPStrength Teuchos::RCP< T >::strength (  )  const [inline]

Strength of the pointer.

Return values:

Definition at line 237 of file Teuchos_RCP.hpp.

template<class T>
bool Teuchos::RCP< T >::is_valid_ptr (  )  const [inline]

Return if the underlying object pointer is still valid or not.

The underlying object will not be valid if the strong count has gone to zero but the weak count thas not.

NOTE: Null is a valid object pointer. If you want to know if there is a non-null object and it is valid then !is_null() && is_valid_ptr() will be true.

Definition at line 245 of file Teuchos_RCP.hpp.

template<class T>
int Teuchos::RCP< T >::strong_count (  )  const [inline]

Return the number of active RCP<> objects that have a "strong" reference to the underlying reference-counted object.

Returns:
If this->get() == NULL then this function returns 0.

Definition at line 255 of file Teuchos_RCP.hpp.

template<class T>
int Teuchos::RCP< T >::weak_count (  )  const [inline]

Return the number of active RCP<> objects that have a "weak" reference to the underlying reference-counted object.

Returns:
If this->get() == NULL then this function returns 0.

Definition at line 263 of file Teuchos_RCP.hpp.

template<class T>
int Teuchos::RCP< T >::total_count (  )  const [inline]

Total count (strong_count() + weak_count()).

Definition at line 271 of file Teuchos_RCP.hpp.

template<class T>
REFCOUNTPTR_INLINE void Teuchos::RCP< T >::set_has_ownership (  ) 

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:

Definition at line 279 of file Teuchos_RCP.hpp.

template<class T>
REFCOUNTPTR_INLINE bool Teuchos::RCP< T >::has_ownership (  )  const

Returns true if this has ownership of object pointed to by this->get() in order to delete it.

See ~RCP() above.

Returns:
If this->get() == 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 287 of file Teuchos_RCP.hpp.

template<class T>
REFCOUNTPTR_INLINE Ptr< T > Teuchos::RCP< T >::release (  ) 

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:

Returns:
Returns the value of this->get()

Definition at line 295 of file Teuchos_RCP.hpp.

template<class T>
RCP< T > Teuchos::RCP< T >::create_weak (  )  const [inline]

Create a new weak RCP object from another (strong) RCP object.

ToDo: Explain this!

Preconditons:

Postconditons:

Definition at line 305 of file Teuchos_RCP.hpp.

template<class T>
RCP< T > Teuchos::RCP< T >::create_strong (  )  const [inline]

Create a new strong RCP object from another (weak) RCP object.

ToDo: Explain this!

Preconditons:

Postconditons:

Definition at line 314 of file Teuchos_RCP.hpp.

template<class T>
template<class T2>
REFCOUNTPTR_INLINE bool Teuchos::RCP< T >::shares_resource ( const RCP< T2 > &  r_ptr  )  const

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 324 of file Teuchos_RCP.hpp.

template<class T>
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 338 of file Teuchos_RCP.hpp.

template<class T>
const RCP< T > & Teuchos::RCP< T >::assert_valid_ptr (  )  const [inline]

If the object pointer is non-null, assert that it is still valid.

If is_null()==false && strong_count()==0, this will throw DanglingReferenceErorr with a great error message.

If is_null()==true, then this will not throw any exception.

In this context, null is a valid object.

Definition at line 348 of file Teuchos_RCP.hpp.

template<class T>
REFCOUNTPTR_INLINE int Teuchos::RCP< T >::count (  )  const

Returns strong_count() [deprecated].

Definition at line 361 of file Teuchos_RCP.hpp.


Friends And Related Function Documentation

template<class T>
enum ENull [related]

Used to initialize a RCP object to NULL using an implicit conversion!

Definition at line 41 of file Teuchos_ENull.hpp.

template<class T>
RCP< T > rcpFromPtr ( const Ptr< T > &  ptr  )  [related]

Create an RCP<T> from a Ptr<T> object.

Definition at line 278 of file Teuchos_PtrDecl.hpp.

template<class T>
RCP< T > rcp ( T *  p,
bool  owns_mem = true 
) [related]

Create a RCP object properly typed.

Parameters:
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.
Preconditions:

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.

Definition at line 435 of file Teuchos_RCP.hpp.

template<class T>
RCP< T > rcp ( T *  p,
Dealloc_T  dealloc,
bool  owns_mem 
) [related]

Initialize from a raw pointer with a deallocation policy.

Parameters:
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.
Preconditions:

Postconditions:

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.

Definition at line 444 of file Teuchos_RCP.hpp.

template<class T>
Teuchos::RCP< T > rcpFromRef ( T &  r  )  [related]

Return a non-owning RCP object from a raw object reference.

Definition at line 452 of file Teuchos_RCP.hpp.

template<class T>
bool is_null ( const RCP< T > &  p  )  [related]

Returns true if p.get()==NULL.

Definition at line 490 of file Teuchos_RCP.hpp.

template<class T>
bool nonnull ( const RCP< T > &  p  )  [related]

Returns true if p.get()!=NULL.

Definition at line 498 of file Teuchos_RCP.hpp.

template<class T>
bool operator== ( const RCP< T > &  p,
ENull   
) [related]

Returns true if p.get()==NULL.

Definition at line 506 of file Teuchos_RCP.hpp.

template<class T>
bool operator!= ( const RCP< T > &  p,
ENull   
) [related]

Returns true if p.get()!=NULL.

Definition at line 514 of file Teuchos_RCP.hpp.

template<class T>
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.

Definition at line 522 of file Teuchos_RCP.hpp.

template<class T>
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.

Definition at line 530 of file Teuchos_RCP.hpp.

template<class T>
RCP< T2 > rcp_implicit_cast ( const RCP< T1 > &  p1  )  [related]

Implicit cast of underlying RCP type from T1* to T2*.

The function will compile only if (T2* p2 = p1.get();) compiles.

This is to be used for conversions up an inheritance hierarchy and from non-const to const and any other standard implicit pointer conversions allowed by C++.

Definition at line 539 of file Teuchos_RCP.hpp.

template<class T>
RCP< T2 > rcp_static_cast ( const RCP< T1 > &  p1  )  [related]

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).

Definition at line 550 of file Teuchos_RCP.hpp.

template<class T>
RCP< T2 > rcp_const_cast ( const RCP< T1 > &  p1  )  [related]

Constant cast of underlying RCP type from T1* to T2*.

This function will compile only if (const_cast<T2*>(p1.get());) compiles.

Definition at line 561 of file Teuchos_RCP.hpp.

template<class T>
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*.

Parameters:
p1 [in] The smart pointer casting from
throw_on_fail [in] If true then if the cast fails (for p1.get()!=NULL) then a std::bad_cast std::exception is thrown with a very informative error message.
Postconditions:

This function will compile only if (dynamic_cast<T2*>(p1.get());) compiles.

Definition at line 572 of file Teuchos_RCP.hpp.

template<class T>
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 
) [related]

Set extra data associated with a RCP object.

Parameters:
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.
If there is a call to this function with the same type of extra data 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:

Note, this function is made a non-member function to be consistent with the non-member get_extra_data() functions.

Definition at line 593 of file Teuchos_RCP.hpp.

template<class T>
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.

Parameters:
p [in] Smart pointer object that extra data is being extraced from.
name [in] Name of the extra data.
Returns:
Returns a const reference to the extra_data object.
Preconditions:

Note, this function must be a non-member function since the client must manually select the first template argument.

Definition at line 605 of file Teuchos_RCP.hpp.

template<class T>
T1 & get_nonconst_extra_data ( RCP< T2 > &  p,
const std::string &  name 
) [related]

Get a non-const reference to extra data associated with a RCP object.

Parameters:
p [in] Smart pointer object that extra data is being extraced from.
name [in] Name of the extra data.
Returns:
Returns a non-const reference to the extra_data object.
Preconditions:

Note, this function must be a non-member function since the client must manually select the first template argument.

Definition at line 618 of file Teuchos_RCP.hpp.

template<class T>
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.

Parameters:
p [in] Smart pointer object that extra data is being extraced from.
name [in] Name of the extra data.
Returns:
Returns a const pointer to the extra_data object if it exists.
Preconditions:

Postconditions:

Note, this function must be a non-member function since the client must manually select the first template argument.

Definition at line 632 of file Teuchos_RCP.hpp.

template<class T>
Ptr< T1 > get_optional_nonconst_extra_data ( RCP< T2 > &  p,
const std::string &  name 
) [related]

Get a pointer to non-const extra data (if it exists) associated with a RCP object.

Parameters:
p [in] Smart pointer object that extra data is being extraced from.
name [in] Name of the extra data.
Returns:
Returns a non-const pointer to the extra_data object.
Preconditions:

Postconditions:

Note, this function must be a non-member function since the client must manually select the first template argument.

Definition at line 646 of file Teuchos_RCP.hpp.

template<class T>
const Dealloc_T & get_dealloc ( const RCP< T > &  p  )  [related]

Return a const reference to the underlying deallocator object.

Preconditions:

Definition at line 659 of file Teuchos_RCP.hpp.

template<class T>
Dealloc_T & get_nonconst_dealloc ( const RCP< T > &  p  )  [related]

Return a non-const reference to the underlying deallocator object.

Preconditions:

Definition at line 667 of file Teuchos_RCP.hpp.

template<class T>
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:

Postconditions:

Definition at line 703 of file Teuchos_RCP.hpp.

template<class T>
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:

Postconditions:

Definition at line 689 of file Teuchos_RCP.hpp.

template<class T>
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().

Definition at line 710 of file Teuchos_RCP.hpp.

template<class T>
Embedded & getNonconstEmbeddedObj ( const RCP< T > &  p  )  [related]

Get a non-const reference to an embedded object that was set by calling rcpWithEmbeddedObjPreDestroy(), rcpWithEmbeddedObjPostDestory(), or rcpWithEmbeddedObj().

Definition at line 718 of file Teuchos_RCP.hpp.

template<class T>
Ptr< const Embedded > getOptionalEmbeddedObj ( const RCP< T > &  p  )  [related]

Get an optional Ptr to a const embedded object if it was set by calling rcpWithEmbeddedObjPreDestroy(), rcpWithEmbeddedObjPostDestory(), or rcpWithEmbeddedObj().

Definition at line 727 of file Teuchos_RCP.hpp.

template<class T>
Ptr< Embedded > getOptionalNonconstEmbeddedObj ( const RCP< T > &  p  )  [related]

Get an optional Ptr to a non-const embedded object if it was set by calling rcpWithEmbeddedObjPreDestroy(), rcpWithEmbeddedObjPostDestory(), or rcpWithEmbeddedObj().

Definition at line 740 of file Teuchos_RCP.hpp.

template<class T>
std::ostream & operator<< ( std::ostream &  out,
const RCP< T > &  p 
) [related]

Output stream inserter.

The implementation of this function just print pointer addresses and therefore puts no restrictions on the data types involved.

Definition at line 752 of file Teuchos_RCP.hpp.


The documentation for this class was generated from the following files:
Generated on Wed May 12 21:24:43 2010 for Teuchos - Trilinos Tools Package by  doxygen 1.4.7