Teuchos::RefCountPtr< T > Class Template Reference
[Reference counting smart pointer class for automatic garbage collection.]

Templated class for reference counted smart pointers (see description). More...

#include <Teuchos_RefCountPtrDecl.hpp>

Inheritance diagram for Teuchos::RefCountPtr< T >:

[legend]
List of all members.

Public Types

typedef T element_type

Public Member Functions

 RefCountPtr (ENull null_arg=null)
 Initialize RefCountPtr<T> to NULL.
 RefCountPtr (const RefCountPtr< T > &r_ptr)
 Initialize from another RefCountPtr<T> object.
template<class T2>
 RefCountPtr (const RefCountPtr< T2 > &r_ptr)
 Initialize from another RefCountPtr<T2> object (implicit conversion only).
 ~RefCountPtr ()
 Removes a reference to a dynamically allocated object and possibly deletes the object if owned.
RefCountPtr< T > & operator= (const RefCountPtr< 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 * release ()
 Release the ownership of the underlying dynamically allocated object.
int count () const
 Return the number of RefCountPtr<> objects that have a reference to the underlying pointer that is being shared.
void set_has_ownership ()
 Give this and other RefCountPtr<> 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.
bool shares_resource (const RefCountPtr< T > &r_ptr) const
 Returns true if the smart pointers share the same underlying reference-counted object.
const RefCountPtr< T > & assert_not_null () const
 Throws std::logic_error if this->get()==NULL, otherwise returns reference to *this.

Private Types

typedef PrivateUtilityPack::RefCountPtr_node node_t

Private Attributes

T * ptr_
node_tnode_

Detailed Description

template<class T>
class Teuchos::RefCountPtr< T >

Templated class for reference counted smart pointers (see description).

This is a class for smart reference counted pointer objects that deletes an object (if the object is owned) that was allocated by new after all refereces to it have been removed.

To see how to use this class see description.

Definition at line 344 of file Teuchos_RefCountPtrDecl.hpp.


Member Typedef Documentation

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

Definition at line 347 of file Teuchos_RefCountPtrDecl.hpp.

template<class T>
typedef PrivateUtilityPack::RefCountPtr_node Teuchos::RefCountPtr< T >::node_t [private]
 

Definition at line 514 of file Teuchos_RefCountPtrDecl.hpp.


Constructor & Destructor Documentation

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

Initialize RefCountPtr<T> to NULL.

This allows clients to write code like:

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

Definition at line 152 of file Teuchos_RefCountPtr.hpp.

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

Initialize from another RefCountPtr<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()
  • If r_ptr.get() != NULL then r_ptr.count() is incremented by 1

Definition at line 159 of file Teuchos_RefCountPtr.hpp.

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

Initialize from another RefCountPtr<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()
  • If r_ptr.get() != NULL then r_ptr.count() is incremented by 1

Definition at line 168 of file Teuchos_RefCountPtr.hpp.

template<class T>
REFCOUNTPTR_INLINE Teuchos::RefCountPtr< T >::~RefCountPtr  ) 
 

Removes a reference to a dynamically allocated object and possibly deletes the object if owned.

Peforms delete ... 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 then internal reference count shared by all the other related RefCountPtr<...> objects for this shared object is deincremented by one. If this->get() == NULL then nothing happens.

Definition at line 177 of file Teuchos_RefCountPtr.hpp.


Member Function Documentation

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

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 (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()
  • If r_ptr.get() != NULL then r_ptr.count() is incremented by 1

Definition at line 184 of file Teuchos_RefCountPtr.hpp.

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

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

Preconditions:

  • this->get() != NULL (throws std::logic_error)

Definition at line 200 of file Teuchos_RefCountPtr.hpp.

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

Dereference the underlying object.

Preconditions:

  • this->get() != NULL (throws std::logic_error)

Definition at line 209 of file Teuchos_RefCountPtr.hpp.

template<class T>
T * Teuchos::RefCountPtr< T >::get  )  const [inline]
 

Get the raw C++ pointer to the underlying object.

Definition at line 218 of file Teuchos_RefCountPtr.hpp.

template<class T>
REFCOUNTPTR_INLINE T * Teuchos::RefCountPtr< T >::release  ) 
 

Release the ownership of the underlying dynamically allocated object.

After this function is called then the client is responsible for calling delete on the returned pointer 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 RefCountPtr<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 224 of file Teuchos_RefCountPtr.hpp.

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

Return the number of RefCountPtr<> objects that have a reference to the underlying pointer that is being shared.

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

Definition at line 232 of file Teuchos_RefCountPtr.hpp.

template<class T>
REFCOUNTPTR_INLINE void Teuchos::RefCountPtr< T >::set_has_ownership  ) 
 

Give this and other RefCountPtr<> objects ownership of the referenced object this->get().

See ~RefCountPtr() above. This function does nothing if this->get() == NULL.

Postconditions:

Definition at line 240 of file Teuchos_RefCountPtr.hpp.

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

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

See ~RefCountPtr() 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 247 of file Teuchos_RefCountPtr.hpp.

template<class T>
REFCOUNTPTR_INLINE bool Teuchos::RefCountPtr< T >::shares_resource const RefCountPtr< T > &  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 255 of file Teuchos_RefCountPtr.hpp.

template<class T>
const RefCountPtr< T > & Teuchos::RefCountPtr< T >::assert_not_null  )  const [inline]
 

Throws std::logic_error if this->get()==NULL, otherwise returns reference to *this.

Definition at line 261 of file Teuchos_RefCountPtr.hpp.


Member Data Documentation

template<class T>
T* Teuchos::RefCountPtr< T >::ptr_ [private]
 

Definition at line 519 of file Teuchos_RefCountPtrDecl.hpp.

template<class T>
node_t* Teuchos::RefCountPtr< T >::node_ [private]
 

Definition at line 520 of file Teuchos_RefCountPtrDecl.hpp.


The documentation for this class was generated from the following files:
Generated on Thu Sep 18 12:41:20 2008 for Teuchos - Trilinos Tools Package by doxygen 1.3.9.1