rwsf::CountingPointer< T > Class Template Reference

Smart pointer class that is intended for use as a handle to a reference-counted body. More...

#include <rwsf/core/CountingPointer.h>

Public Types
typedef T *	PointerType
typedef T &	ReferenceType

Public Member Functions
	CountingPointer (PointerType pointer=0, AtomicCounter *counterP=0)
	CountingPointer (const CountingPointer< T > &second)
	~CountingPointer (void)
PointerType	get (void) const
bool	isValid (void) const
template<class O >
	operator CountingPointer< O > ()
	operator typename CountingPointer< T >::UnspecifiedBoolType () const
ReferenceType	operator* (void) const
PointerType	operator-> (void) const
CountingPointer< T > &	operator= (const CountingPointer< T > &second)
CountingPointer< T > &	operator= (PointerType pointer)
void	swapWith (CountingPointer< T > &second)
void	validate (void) const

Related Functions
(Note that these are not member functions.)
template<class T , class O >
T	cCast (const CountingPointer< O > &pointer)
template<class T , class O >
T	constCast (const CountingPointer< O > &pointer)
template<class T , class O >
T	dynamicCast (const CountingPointer< O > &pointer)
template<class T , class O >
bool	operator!= (const CountingPointer< T > &first, const CountingPointer< O > &second)
template<class T , class O >
bool	operator!= (const CountingPointer< T > &first, const O *second)
template<class T , class O >
bool	operator!= (const T *first, const CountingPointer< O > &second)
template<class T , class O >
bool	operator< (const CountingPointer< T > &first, const CountingPointer< O > &second)
template<class T , class O >
bool	operator<= (const CountingPointer< T > &first, const CountingPointer< O > &second)
template<class T , class O >
bool	operator== (const CountingPointer< T > &first, const CountingPointer< O > &second)
template<class T , class O >
bool	operator== (const CountingPointer< T > &first, const O *second)
template<class T , class O >
bool	operator== (const T *first, const CountingPointer< O > &second)
template<class T , class O >
bool	operator> (const CountingPointer< T > &first, const CountingPointer< O > &second)
template<class T , class O >
bool	operator>= (const CountingPointer< T > &first, const CountingPointer< O > &second)
template<class T , class O >
T	reinterpretCast (const CountingPointer< O > &pointer)
template<class T , class O >
T	staticCast (const CountingPointer< O > &pointer)

Detailed Description

template<typename T>
class rwsf::CountingPointer< T >

Deprecated:

Use RefCountingPointer instead.

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

rwsf::CountingPointer is a non-intrusive smart pointer type, which maintains a parallel counter to the body. For a class that assumes the body maintains the count, see rwsf::RefCountingPointer.

See also

rwsf::RefCountingPointer

Member Typedef Documentation

template<typename T>

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

A typedef to the underlying raw pointer type.

template<typename T>

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

A typedef to the underlying reference type.

Constructor & Destructor Documentation

template<typename T>

rwsf::CountingPointer< T >::CountingPointer	(	PointerType	pointer = 0,
		AtomicCounter *	counterP = 0
	)

Constructs a pointer instance that manages references for the specified body instance. If pointer is null (the default case), an invalid CountingPointer instance is created, and counterP is ignored. If counterP is null (the default case), a new AtomicCounter instance is created with an initial count of one.

If the CountingPointer fails to initialize, and counterP is null, the memory associated with pointer is deallocated in order to prevent memory leaks. If counterP is non-null, the pointer is not affected, and the user is responsible for releasing any associated resources.

Parameters:

• pointer - The T instance to be managed by this pointer.
• counterP - An atomic counter representing the count on the referenced object.

template<typename T>

rwsf::CountingPointer< T >::CountingPointer

(

const CountingPointer< T > &

second

)

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

template<typename T>

rwsf::CountingPointer< T >::~CountingPointer

(

void

)

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

Member Function Documentation

template<typename T>

PointerType rwsf::CountingPointer< T >::get

(

void

)

const

Deprecated:

Retrieves the handle's pointer value without validating it. Throws no exceptions.

Note

The memory associated with this pointer may be deallocated if the counting pointer is instructed to release it. In general, using this method is not recommended.

template<typename T>

bool rwsf::CountingPointer< T >::isValid

(

void

)

const

Returns true if pointer is non-null, otherwise returns false. Throws no exceptions.

template<typename T>

template<class O >

rwsf::CountingPointer< T >::operator CountingPointer< O >

(

)

Conversion operator. Tries to return the contained pointer as a pointer of type O. If the conversion is not possible, returns an invalid CountingPointer.

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 users use the explicit cast methods associated with this class in order to convert between different CountingPointer types.

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

template<typename T>

rwsf::CountingPointer< T >::operator typename CountingPointer< 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<typename T>

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

(

void

)

const

Returns the underlying body as a reference after verifying the pointer is valid.

Exceptions

NullPointerException

if the body is invalid.

template<typename T>

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

(

void

)

const

Returns the underlying body as a pointer after verifying the pointer is valid.

Exceptions

NullPointerException

if the body is invalid.

template<typename T>

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

(

const CountingPointer< T > &

second

)

Attaches to the body specified by 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<typename T>

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

(

PointerType

pointer

)

Attaches to the body specifed by pointer 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<typename T>

void rwsf::CountingPointer< T >::swapWith

(

CountingPointer< T > &

second

)

Deprecated:

Swaps bodies (if any) with another handle. Throws no exceptions.

template<typename T>

void rwsf::CountingPointer< T >::validate

(

void

)

const

Deprecated:

Use operator*() instead.

Checks if the pointer is null, and throws an rwsf::NullPointerException if it is.

Friends And Related Function Documentation

template<class T , class O >

T cCast ( const CountingPointer< 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 CountingPointer type.

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

template<class T , class O >

T constCast ( const CountingPointer< 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 CountingPointer type.

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

template<class T , class O >

T dynamicCast ( const CountingPointer< 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 CountingPointer type. The returned pointer is associated with null if the dynamic_cast fails.

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

template<class T , class O >

bool operator!= ( const CountingPointer< T > &  first, const CountingPointer< O > &  second  )

related

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

Note

operator!=() is defined in terms of operator==(). Users who want to change the behavior of equality/inequality for specializations of CountingPointer only need to overload operator==().

template<class T , class O >

bool operator!= ( const CountingPointer< T > &  first, const O *  second  )

related

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

Note

operator!=() is defined in terms of operator==(). Users who want to change the behavior of equality/inequality for specializations of CountingPointer only need to overload operator==().

template<class T , class O >

bool operator!= ( const T *  first, const CountingPointer< O > &  second  )

related

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

Note

operator!=() is defined in terms of operator==(). Users who want to change the behavior of equality/inequality for specializations of CountingPointer only need to overload operator==().

template<class T , class O >

bool operator< ( const CountingPointer< T > &  first, const CountingPointer< 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, otherwise returns false.

template<class T , class O >

bool operator<= ( const CountingPointer< T > &  first, const CountingPointer< 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, otherwise returns false.

Note

operator<=() is defined in terms of operator<(). Users who want to change the behavior of greater-than-equals/less-than-equals for specializations of CountingPointer only need to overload operator<().

template<class T , class O >

bool operator== ( const CountingPointer< T > &  first, const CountingPointer< 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, otherwise returns false.

template<class T , class O >

bool operator== ( const CountingPointer< 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, otherwise returns false.

template<class T , class O >

bool operator== ( const T *  first, const CountingPointer< 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, otherwise returns false.

template<class T , class O >

bool operator> ( const CountingPointer< T > &  first, const CountingPointer< O > &  second  )

related

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

Note

operator>() is defined in terms of operator<(). Users who want to change the behavior of greater-than/less-than for specializations of CountingPointer only need to overload operator<().

template<class T , class O >

bool operator>= ( const CountingPointer< T > &  first, const CountingPointer< 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, otherwise returns false.

Note

operator<=() is defined in terms of operator<(). Users who want to change the behavior of greater-than-equals/less-than-equals for specializations of CountingPointer only need to overload operator<().

template<class T , class O >

T reinterpretCast ( const CountingPointer< 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 CountingPointer type.

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

template<class T , class O >

T staticCast ( const CountingPointer< 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 CountingPointer type.

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