Rogue Wave web site:  Home Page  |  Main Documentation Page

rwsf::RefCountingPointer< T > Class Template Reference
[Core Design Patterns]

A smart pointer that is a handle to a reference-counting body, deleting the body instance when the reference count reaches zero. More...

#include <rwsf/core/RefCountingPointer.h>

List of all members.

Public Types
typedef T *	PointerType
typedef T &	ReferenceType
Public Member Functions
	RefCountingPointer (PointerType pointer=0)
	RefCountingPointer (const RefCountingPointer< T > &second)
template<typename O >
	RefCountingPointer (const RefCountingPointer< O > &second)
	~RefCountingPointer (void)
RefCountingPointer< T > &	operator= (const RefCountingPointer< T > &second)
template<typename O >
RefCountingPointer< T > &	operator= (const RefCountingPointer< O > &second)
RefCountingPointer< T > &	operator= (PointerType second)
PointerType	operator-> (void) const
ReferenceType	operator* (void) const
	operator typename RefCountingPointer< T >::UnspecifiedBoolType () const
bool	isValid (void) const
Related Functions
(Note that these are not member functions.)
template<class T , class O >
bool	operator== (const RefCountingPointer< T > &first, const RefCountingPointer< O > &second)
template<class T , class O >
bool	operator== (const RefCountingPointer< T > &first, const O *second)
template<class T , class O >
bool	operator== (const T *first, const RefCountingPointer< O > &second)
template<class T , class O >
bool	operator!= (const T *first, const RefCountingPointer< O > &second)
template<class T , class O >
bool	operator!= (const RefCountingPointer< T > &first, const RefCountingPointer< O > &second)
template<class T , class O >
bool	operator!= (const RefCountingPointer< T > &first, const O *second)
template<class T >
bool	operator!= (const void *first, const RefCountingPointer< T > &second)
template<class T , class O >
bool	operator< (const RefCountingPointer< T > &first, const RefCountingPointer< O > &second)
template<class T , class O >
bool	operator> (const RefCountingPointer< T > &first, const RefCountingPointer< O > &second)
template<class T , class O >
bool	operator<= (const RefCountingPointer< T > &first, const RefCountingPointer< O > &second)
template<class T , class O >
bool	operator>= (const RefCountingPointer< T > &first, const RefCountingPointer< O > &second)
template<class T , class O >
T	cCast (const RefCountingPointer< O > &pointer)
template<class T , class O >
T	constCast (const RefCountingPointer< O > &pointer)
template<class T , class O >
T	dynamicCast (const RefCountingPointer< O > &pointer)
template<class T , class O >
T	reinterpretCast (const RefCountingPointer< O > &pointer)
template<class T , class O >
T	staticCast (const RefCountingPointer< O > &pointer)

---

Detailed Description

template<class T>
class rwsf::RefCountingPointer< T >

A smart pointer class that is intended for use as a handle to a reference-counting body. Each time an instance of this class is bound to a body instance, it increments the reference count maintained by that body. Each time it detaches from a body instance, it decrements the body's reference count; if the reference count reaches zero, it deletes the body instance. The reference counting relieves clients of the need to track when it is safe to delete a body instance.

The class T specified as a template parameter must provide member functions for incrementing and decrementing the reference count, and is responsible for deleting the instance of T when the count reaches 0.

 void addRef();
 void releaseRef();

The class rwsf::RefCountingObject can be used as a base class in order to provide this functionality in user-defined types.

Note:

For classes that do not implement the addRef() and releaseRef() methods above, see rwsf::CountingPointer for a non-intrusive smart-pointer solution.

See also:

rwsf::CountingPointer, rwsf::RefCountingObject

---

Member Typedef Documentation

template<class T >

typedef T* rwsf::RefCountingPointer< T >::PointerType

Typedef to the underlying raw pointer type.

template<class T >

typedef T& rwsf::RefCountingPointer< T >::ReferenceType

Typedef to the underlying reference type.

---

Constructor & Destructor Documentation

template<class T >

rwsf::RefCountingPointer< T >::RefCountingPointer

(

PointerType

pointer = 0

)

Attaches to and increments the reference-count on a body.

template<class T >

rwsf::RefCountingPointer< T >::RefCountingPointer

(

const RefCountingPointer< T > &

second

)

[inline]

Attaches to and increments the reference-count on the body of second.

template<class T >

template<typename O >

rwsf::RefCountingPointer< T >::RefCountingPointer

(

const RefCountingPointer< O > &

second

)

[inline]

Attaches to and increments the reference-count on the body of second.

Note:

This method performs a dynamic_cast on O in order to convert it to a type T. This may be an expensive operation if a dynamic_cast is not needed for the conversion. It is recommended that you use the explicit cast methods associated with this class in order to convert between different RefCountingPointer types. For instance, static_cast<T>(ptr) , dynamic_cast<T>(ptr) , const_cast<T>(ptr) , etc.

Note that the automatic dynamic_cast associated with this method may be removed in a future release and should not be relied upon. You can define the macro RWSF_CORE_DISABLE_DEPRECATED before including this header file in order to check your code for conversions that should use an explicit cast.

template<class T >

rwsf::RefCountingPointer< T >::~RefCountingPointer

(

void

)

Decrements the body's reference count and deletes it if there are no other references.

---

Member Function Documentation

template<class T >

bool rwsf::RefCountingPointer< T >::isValid

(

void

)

const

Returns true if the underlying pointer is non-zero, false otherwise.

template<class T >

rwsf::RefCountingPointer< T >::operator typename RefCountingPointer< T >::UnspecifiedBoolType

(

)

const [inline]

Returns an unspecified boolean type to allow for testing if the associated pointer is null. The boolean type is not specified in order to avoid unintended implicit conversions.

template<class T >

ReferenceType rwsf::RefCountingPointer< T >::operator*

(

void

)

const

Verifies that the underlying is not null, dereferences, and returns the underlying body.

Exceptions:

NullPointerException

If the underlying pointer is null.

template<class T >

PointerType rwsf::RefCountingPointer< T >::operator->

(

void

)

const

Verifies that the underlying body is not null, and returns an instance of the underlying body.

Exceptions:

NullPointerException

If the underlying pointer is null.

template<class T >

RefCountingPointer<T>& rwsf::RefCountingPointer< T >::operator=

(

PointerType

second

)

Attaches to the body of second and increments its reference count If a body is already associated with this, its count is decremented, and the body is deleted if there are no other references.

template<class T >

template<typename O >

RefCountingPointer<T>& rwsf::RefCountingPointer< T >::operator=

(

const RefCountingPointer< O > &

second

)

[inline]

Attaches to the body of second, and increments its reference count. If a body is already associated with this, its count is decremented, and the body is deleted if there are no other references.

Note:

This method performs a dynamic_cast on O in order to convert it to a type T. This may be an expensive operation if a dynamic_cast is not needed for the conversion. It is recommended that you use the explicit cast methods associated with this class in order to convert between different RefCountingPointer types.

Note that the automatic dynamic_cast associated with this method may be removed in a future release, and should not be relied upon. You can define the macro RWSF_CORE_DISABLE_DEPRECATED before including this header file in order to check your code for conversions that should use an explicit cast.

template<class T >

RefCountingPointer<T>& rwsf::RefCountingPointer< T >::operator=

(

const RefCountingPointer< T > &

second

)

[inline]

Attaches to the body of second, and increments its reference-count. If a body is already associated with this, its count is decremented, and the body is deleted if there are no other references.

---

Friends And Related Function Documentation

template<class T , class O >

T cCast

(

const RefCountingPointer< O > &

pointer

)

[related]

Performs a C-style cast on the raw pointer associated with pointer, converting it to type T::PointerType. T is assumed to be a RefCountingPointer type.

 RefCountingPointer<Base> b = ...;
 RefCountingPointer<Derived> d = cCast<RefCountingPointer<Derived> >(b);

template<class T , class O >

T constCast

(

const RefCountingPointer< O > &

pointer

)

[related]

Performs a const_cast on the raw pointer associated with pointer, converting it to type T::PointerType. T is assumed to be a RefCountingPointer type.

 RefCountingPointer<const Base> cb = ...;
 RefCountingPointer<Base> b = constCast<RefCountingPointer<Base> >(cb);

template<class T , class O >

T dynamicCast

(

const RefCountingPointer< O > &

pointer

)

[related]

Performs a dynamic_cast on the raw pointer associated with pointer, converting it to type T::PointerType. T is assumed to be a RefCountingPointer type. The returned pointer will be associated with null if the dynamic_cast fails.

 RefCountingPointer<Base> b = ...;
 RefCountingPointer<Derived> d = dynamicCast<RefCountingPointer<Derived> >(b);

template<class T >

bool operator!=	(	const void *	first,
		const RefCountingPointer< T > &	second
	)			[related]

Inequality operator. Verifies that the pointer associated with first is equal to the pointer associated with second. Returns true if they are equal, false otherwise.

Note:

operator!=() is defined in terms of operator==(). To change the behavior of equality/inequality for specializations of RefCountingPointer, just overload operator==().

template<class T , class O >

bool operator!=	(	const RefCountingPointer< T > &	first,
		const O *	second
	)			[related]

Inequality operator. Verifies that the pointer associated with first is equal to the pointer associated with second. Returns true if they are equal, false otherwise.

Note:

operator!=() is defined in terms of operator==(). To change the behavior of equality/inequality for specializations of RefCountingPointer, just overload operator==().

template<class T , class O >

bool operator!=	(	const RefCountingPointer< T > &	first,
		const RefCountingPointer< O > &	second
	)			[related]

Inequality operator. Verifies that the pointer associated with first is equal to the pointer associated with second. Returns true if they are equal, false otherwise.

Note:

operator!=() is defined in terms of operator==(). To change the behavior of equality/inequality for specializations of RefCountingPointer, just overload operator==().

template<class T , class O >

bool operator!=	(	const T *	first,
		const RefCountingPointer< O > &	second
	)			[related]

Inequality operator. Verifies that the pointer associated with first is equal to the pointer associated with second. Returns true if they are equal, false otherwise.

Note:

operator!=() is defined in terms of operator==(). To change the behavior of equality/inequality for specializations of RefCountingPointer, just overload operator==().

template<class T , class O >

bool operator<	(	const RefCountingPointer< T > &	first,
		const RefCountingPointer< O > &	second
	)			[related]

Less than operator. Verifies that the pointer associated with first is less than the pointer associated with second. Returns true if first is less than second, false otherwise.

template<class T , class O >

bool operator<=	(	const RefCountingPointer< T > &	first,
		const RefCountingPointer< O > &	second
	)			[related]

Less than or equal operator. Verifies that the pointer associated with first is less than or equal to the pointer associated with second. Returns true if first is less than or equal to second, false otherwise.

Note:

operator<=() is defined in terms of operator<(). To change the behavior of equality/inequality for specializations of RefCountingPointer, just overload operator<().

template<class T , class O >

bool operator==	(	const T *	first,
		const RefCountingPointer< O > &	second
	)			[related]

Equality operator. Verifies that the pointer associated with first is equal to the pointer associated with second. Returns true if they are equal, false otherwise.

template<class T , class O >

bool operator==	(	const RefCountingPointer< T > &	first,
		const O *	second
	)			[related]

Equality operator. Verifies that the pointer associated with first is equal to the pointer associated with second. Returns true if they are equal, false otherwise.

template<class T , class O >

bool operator==	(	const RefCountingPointer< T > &	first,
		const RefCountingPointer< O > &	second
	)			[related]

Equality operator. Verifies that the pointer associated with first is equal to the pointer associated with second. Returns true if they are equal, false otherwise.

template<class T , class O >

bool operator>	(	const RefCountingPointer< T > &	first,
		const RefCountingPointer< O > &	second
	)			[related]

Greater than operator. Verifies that the pointer associated with first is less than the pointer associated with second. Returns true if first is greater than second, false otherwise.

Note:

operator>() is defined in terms of operator<(). To change the behavior of equality/inequality for specializations of RefCountingPointer, just overload operator<().

template<class T , class O >

bool operator>=	(	const RefCountingPointer< T > &	first,
		const RefCountingPointer< O > &	second
	)			[related]

Greater than or equal operator. Verifies that the pointer associated with first is greater than or equal to the pointer associated with second. Returns true if first is greater than or equal to second, false otherwise.

Note:

operator>=() is defined in terms of operator<(). To change the behavior of equality/inequality for specializations of RefCountingPointer, just overload operator<().

template<class T , class O >

T reinterpretCast

(

const RefCountingPointer< O > &

pointer

)

[related]

Performs a reinterpret_cast on the raw pointer associated with pointer, converting it to type T::PointerType. T is assumed to be a RefCountingPointer type.

 RefCountingPointer<Base> b = ...;
 RefCountingPointer<Derived> d = dynamicCast<RefCountingPointer<Derived> >(b);

template<class T , class O >

T staticCast

(

const RefCountingPointer< O > &

pointer

)

[related]

Performs a static_cast on the raw pointer associated with pointer, converting it to type T::PointerType. T is assumed to be a RefCountingPointer type.

 RefCountingPointer<Base> b = ...;
 RefCountingPointer<Derived> d = staticCast<RefCountingPointer<Derived> >(b);