rwsf::RefCountingPointer< T > Class Template Reference

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>

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)
bool	isValid (void) const
	operator typename RefCountingPointer< T >::UnspecifiedBoolType () const
ReferenceType	operator* (void) const
PointerType	operator-> (void) const
RefCountingPointer< T > &	operator= (const RefCountingPointer< T > &second)
template<typename O >
RefCountingPointer< T > &	operator= (const RefCountingPointer< O > &second)
RefCountingPointer< T > &	operator= (PointerType second)

Related Functions
(Note that these are not member functions.)
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 >
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 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 RefCountingPointer< O > &second)
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, staticCast(const RefCountingPointer<O>&), dynamicCast(const RefCountingPointer<O>&), constCast(const RefCountingPointer<O>&), 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= ( 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.

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=

(

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.

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 , 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

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 >

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