Reference counting smart pointer class for automatic garbage collection.

ToDo: Put in link to latex paper and shorten this discussion (perhaps just the quickstart). More...

Classes
class	Teuchos::DeallocDelete< T >
	Policy class for deallocator that uses delete to delete a pointer which is used by RefCountPtr. More...
class	Teuchos::RefCountPtr< T >
	Templated class for reference counted smart pointers. More...
Enumerations
enum	Teuchos::ENull { Teuchos::null }
	Used to initialize a RefCountPtr object to NULL using an implicit conversion! More...
Functions
template<class T>
RefCountPtr< T >	Teuchos::rcp (T *p, bool owns_mem=true)
	Create a RefCountPtr object properly typed.
template<class T, class Dealloc_T>
RefCountPtr< T >	Teuchos::rcp (T *p, Dealloc_T dealloc, bool owns_mem)
	Initialize from a raw pointer with a deallocation policy.
template<class T2, class T1>
RefCountPtr< T2 >	Teuchos::rcp_implicit_cast (const RefCountPtr< T1 > &p1)
	Implicit cast of underlying RefCountPtr type from T1* to T2*.
template<class T2, class T1>
RefCountPtr< T2 >	Teuchos::rcp_static_cast (const RefCountPtr< T1 > &p1)
	Static cast of underlying RefCountPtr type from T1* to T2*.
template<class T2, class T1>
RefCountPtr< T2 >	Teuchos::rcp_const_cast (const RefCountPtr< T1 > &p1)
	Constant cast of underlying RefCountPtr type from T1* to T2*.
template<class T2, class T1>
RefCountPtr< T2 >	Teuchos::rcp_dynamic_cast (const RefCountPtr< T1 > &p1)
	Dynamic cast of underlying RefCountPtr type from T1* to T2*.
template<class T1, class T2>
void	Teuchos::set_extra_data (const T1 &extra_data, const std::string &name, RefCountPtr< T2 > *p, bool force_unique=true)
	Set extra data associated with a RefCountPtr object.
template<class T1, class T2>
T1 &	Teuchos::get_extra_data (RefCountPtr< T2 > &p, const std::string &name)
	Get a non-const reference to extra data associated with a RefCountPtr object.
template<class T1, class T2>
const T1 &	Teuchos::get_extra_data (const RefCountPtr< T2 > &p, const std::string &name)
	Get a const reference to extra data associated with a RefCountPtr object.
template<class Dealloc_T, class T>
Dealloc_T &	Teuchos::get_dealloc (RefCountPtr< T > &p)
	Return a non-const reference to the underlying deallocator object.
template<class Dealloc_T, class T>
const Dealloc_T &	Teuchos::get_dealloc (const RefCountPtr< T > &p)
	Return a const reference to the underlying deallocator object.

---

Detailed Description

ToDo: Put in link to latex paper and shorten this discussion (perhaps just the quickstart).

---

Enumeration Type Documentation

enum ENull

Used to initialize a RefCountPtr object to NULL using an implicit conversion! Enumeration values: null  Definition at line 87 of file Teuchos_RefCountPtrDecl.hpp.

---

Function Documentation

template<class T> Teuchos::RefCountPtr< T > Teuchos::rcp (  T *  p, bool  owns_mem = true )  [inline]

Create a RefCountPtr 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 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. Examples: RefCountPtr/cxx_main.cpp. Definition at line 296 of file Teuchos_RefCountPtr.hpp.

template<class T, class Dealloc_T> Teuchos::RefCountPtr< T > Teuchos::rcp (  T *  p, Dealloc_T  dealloc, bool  owns_mem )  [inline]

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. Postconditions: The function void Dealloc_T::free(T* p) exists. Postconditions: return.get() == p If p == NULL then return.count() == 0 return.has_ownership() == false else 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 ~RefCountPtr()). It is vitually important that if owns_mem == true that the address p that is 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 304 of file Teuchos_RefCountPtr.hpp.

template<class T2, class T1> REFCOUNTPTR_INLINE Teuchos::RefCountPtr< T2 > Teuchos::rcp_implicit_cast (  const RefCountPtr< T1 > &  p1  )

Implicit cast of underlying RefCountPtr 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 312 of file Teuchos_RefCountPtr.hpp.

template<class T2, class T1> REFCOUNTPTR_INLINE Teuchos::RefCountPtr< T2 > Teuchos::rcp_static_cast (  const RefCountPtr< T1 > &  p1  )

Static cast of underlying RefCountPtr 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<tt><t2>(p1). Definition at line 327 of file Teuchos_RefCountPtr.hpp.

template<class T2, class T1> REFCOUNTPTR_INLINE Teuchos::RefCountPtr< T2 > Teuchos::rcp_const_cast (  const RefCountPtr< T1 > &  p1  )

Constant cast of underlying RefCountPtr type from T1* to T2*. This function will compile only if (const_cast<T2*>(p1.get());) compiles. Definition at line 342 of file Teuchos_RefCountPtr.hpp.

template<class T2, class T1> REFCOUNTPTR_INLINE Teuchos::RefCountPtr< T2 > Teuchos::rcp_dynamic_cast (  const RefCountPtr< T1 > &  p1  )

Dynamic cast of underlying RefCountPtr type from T1* to T2*. This function will compile only if (dynamic_cast<T2*>(p1.get());) compiles. Definition at line 357 of file Teuchos_RefCountPtr.hpp.

template<class T1, class T2> REFCOUNTPTR_INLINE void Teuchos::set_extra_data (  const T1 &  extra_data, const std::string &  name, RefCountPtr< T2 > *  p, bool  force_unique = true )

Set extra data associated with a RefCountPtr 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 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 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 the underlying reference-counted object is deleted before any of the extra data that has been associated with this object. The extra data objects will then be destoried in a first-in basis. In other words, the first extra data object added will be deleted first, the second extra data object will be deleted second and so on. This must be considered when multiple pieces of extra data are being added if the order of distruction is significant. Preconditions: p->get() != NULL (throws std::logic_error) If this function has already been called with the same template type T1 for extra_data and the same string name and force_unique==true, then an std::invalid_argument exception will be thrown. Note, this function is made a non-member function to be consistent with the non-member get_extra_data() functions. Definition at line 373 of file Teuchos_RefCountPtr.hpp.

template<class T1, class T2> REFCOUNTPTR_INLINE T1 & Teuchos::get_extra_data (  RefCountPtr< T2 > &  p, const std::string &  name )

Get a non-const reference to extra data associated with a RefCountPtr 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: p.get() != NULL (throws std::logic_error) 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. Definition at line 381 of file Teuchos_RefCountPtr.hpp.

template<class T1, class T2> REFCOUNTPTR_INLINE const T1 & Teuchos::get_extra_data (  const RefCountPtr< T2 > &  p, const std::string &  name )

Get a const reference to extra data associated with a RefCountPtr 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: p.get() != NULL (throws std::logic_error) 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. Also note that this const version is a false sense of security since a client can always copy a const RefCountPtr object into a non-const object and then use the non-const version to change the data. However, its presence will help to avoid some types of accidental changes to this extra data. Definition at line 389 of file Teuchos_RefCountPtr.hpp.

template<class Dealloc_T, class T> REFCOUNTPTR_INLINE Dealloc_T & Teuchos::get_dealloc (  RefCountPtr< T > &  p  )

Return a non-const reference to the underlying deallocator object. Preconditions: p.get() != NULL (throws std::logic_error) The deallocator object type used to construct p is same as Dealloc_T (throws std::logic_error) Definition at line 398 of file Teuchos_RefCountPtr.hpp.

template<class Dealloc_T, class T> const Dealloc_T & Teuchos::get_dealloc (  const RefCountPtr< T > &  p  )  [inline]

Return a const reference to the underlying deallocator object. Preconditions: p.get() != NULL (throws std::logic_error) The deallocator object type used to construct p is same as Dealloc_T (throws std::logic_error) Note that the const version of this function provides only a very ineffective attempt to avoid accidental changes to the deallocation object. A client can always just create a new non-const RefCountPtr<T> object from any const RefCountPtr<T> object and then call the non-const version of this function. Definition at line 415 of file Teuchos_RefCountPtr.hpp.

---