Template smart pointer (reference-counted, auto-delete, optionally thread-safe). More...

Classes
class	SmartShared
	Shared implementation of the smart pointer. More...

Public Member Functions
	QtlSmartPointer (T *p=0)
	Default constructor using an optional unmanaged object. More...

	QtlSmartPointer (const QtlSmartPointer< T, MUTEXLOCKER > &sp)
	Copy constructor. More...

	~QtlSmartPointer ()
	Destructor. More...

template<typename NEWMUTEXLOCKER >
QtlSmartPointer< T, NEWMUTEXLOCKER >	changeMutex ()
	Change mutex locker type. More...

void	clear ()
	Clear this instance of the smart pointer. More...

int	count () const
	Get the reference count value. More...

template<typename ST >
QtlSmartPointer< ST, MUTEXLOCKER >	downcast ()
	Downcast operation. More...

bool	isNull () const
	Check if this smart pointer is a null pointer. More...

bool	operator!= (const QtlSmartPointer< T, MUTEXLOCKER > &sp) const
	Unequality operator. More...

T &	operator* () const
	Accessor operator. More...

T *	operator-> () const
	Redirection operator. More...

const QtlSmartPointer< T, MUTEXLOCKER > &	operator= (const QtlSmartPointer< T, MUTEXLOCKER > &sp)
	Assignment between smart pointers. More...

const QtlSmartPointer< T, MUTEXLOCKER > &	operator= (T *p)
	Assignment from a standard pointer `T*`. More...

bool	operator== (const QtlSmartPointer< T, MUTEXLOCKER > &sp) const
	Equality operator. More...

T *	pointer () const
	Get a standard pointer `T*` on the pointed object. More...

T *	release ()
	Release the pointed object from the smart pointer management. More...

void	reset (T *p=0)
	Deallocate the previous pointed object and set the pointer to the new object. More...

template<typename ST >
QtlSmartPointer< ST, MUTEXLOCKER >	upcast ()
	Upcast operation. More...

Private Attributes
SmartShared *	_shared
	QtlSmartPointer private field simply points to a SmartShared instance. More...

Detailed Description

template<typename T, class MUTEXLOCKER>
class QtlSmartPointer< T, MUTEXLOCKER >

Template smart pointer (reference-counted, auto-delete, optionally thread-safe).

The QtlSmartPointer template class is an implementation of the smart pointer design pattern. A smart pointer implements the semantics of a standard pointer with automatic memory management.

Smart pointer objects pointing to the same object can be assigned like any standard pointer (elementary type). A reference counter on the pointed object is maintained and the pointed object is automatically deleted when no more smart pointer references the object.

Limitation: The automatic deletion of the pointed object occurs only when the reference counter reaches zero. There are cases where this never happens. Typically, when two objects reference each other but are no longer referenced anywhere else, these two objects are lost forever and will never be deleted. So, beware that smart pointers do not prevent from memory leaks in some pathological cases. As usual, be sure to design safely.

Limitation: Because the automatic deletion is performed using the operator delete, smart pointers cannot point on array types since arrays must be deleted using the operator delete[].

The standard operators for elementary type pointers also exist for smart pointers (assignment, comparison, dereferencing, etc.)

A smart pointer can be null, this is the default value. In this case, the smart pointer does not reference any object. To test if a smart pointer is a null pointer, use the method isNull(). Do not use comparisons such as p == 0, the result will be incorrect.

The QtlSmartPointer template class can be made thread-safe using a mutex. The type of mutex to use is given by the template parameter MUTEXLOCKER.

Template Parameters

T	The type of the pointed object. Cannot be an array type.
MUTEXLOCKER	A class which is used to synchronize access to the smart pointer internal state. Typically either QtlMutexLocker (for thread-safe smart pointers) or QtlNullMutexLocker (for non-thread-safe smart pointers).

Constructor & Destructor Documentation

◆ QtlSmartPointer() [1/2]

template<typename T, class MUTEXLOCKER>

QtlSmartPointer< T, MUTEXLOCKER >::QtlSmartPointer ( T * p = 0 )

inline

Default constructor using an optional unmanaged object.

The optional argument p can be either 0 (null pointer) or the address of an unmanaged dynamically allocated object (i.e. which has been allocated using the operator new). In this case, unmanaged means that the object must not be already controlled by another set of smart pointers.

This constructor is typically used in combination with the operator new to allocate an object which is immediatly managed by smart pointers.

Example:

QtlSmartPointer<Foo,QtlMutexLocker> ptr(new Foo(...));

Parameters

[in] p A pointer to an object of class T. The default value is 0, the null pointer. In this case, the smart pointer is a null pointer.

◆ QtlSmartPointer() [2/2]

template<typename T, class MUTEXLOCKER>

QtlSmartPointer< T, MUTEXLOCKER >::QtlSmartPointer ( const QtlSmartPointer< T, MUTEXLOCKER > & sp )

inline

Copy constructor.

This object references the same T object as sp. If sp is a null pointer, this object is also a null pointer.

Parameters

[in] sp Another smart pointer instance.

◆ ~QtlSmartPointer()

template<typename T , class MUTEXLOCKER >

QtlSmartPointer< T, MUTEXLOCKER >::~QtlSmartPointer ( )

Destructor.

If this object is not a null pointer, the reference counter is decremented. When the reference counter reaches zero, the pointed object is automatically deleted.

Member Function Documentation

◆ operator=() [1/2]

template<typename T, class MUTEXLOCKER>

const QtlSmartPointer< T, MUTEXLOCKER > & QtlSmartPointer< T, MUTEXLOCKER >::operator= ( const QtlSmartPointer< T, MUTEXLOCKER > & sp )

Assignment between smart pointers.

After the assignment, this object references the same T object as sp. If this object was previously not the null pointer, the reference counter of the previously referenced T object is decremented. If the reference counter reaches zero, the previously pointed object is automatically deleted.

Parameters

[in] sp The value to assign.

Returns: A reference to this object.

◆ operator=() [2/2]

template<typename T, class MUTEXLOCKER>

const QtlSmartPointer< T, MUTEXLOCKER > & QtlSmartPointer< T, MUTEXLOCKER >::operator= ( T * p )

Assignment from a standard pointer T*.

The pointed T object becomes managed by this smart pointer.

The standard pointer p can be either 0 (null pointer) or the address of an unmanaged dynamically allocated object (i.e. which has been allocated using the operator new). In this case, unmanaged means that the object must not be already controlled by another set of smart pointers.

After the assignment, this object references the T object. If this smart pointer object was previously not the null pointer, the reference counter of the previously referenced T object is decremented. If the reference counter reaches zero, the previously pointed object is automatically deleted.

Parameters

[in] p A pointer to an object of class T.

Returns: A reference to this object.

◆ operator==()

template<typename T, class MUTEXLOCKER>

bool QtlSmartPointer< T, MUTEXLOCKER >::operator== ( const QtlSmartPointer< T, MUTEXLOCKER > & sp ) const

inline

Equality operator.

Check if this smart pointer and the sp smart pointer point to same object.

Caveat: Null pointers are not reliably compared with this operator. It shall not be used to compare against null pointer. Do not check == 0, use the method isNull() instead. Also, if both smart pointers are null pointers, the result is unpredictable, it can be true or false.

Parameters

[in] sp A smart pointer to compare with.

Returns: True if both smart pointers reference the same object and false otherwise.

◆ operator!=()

template<typename T, class MUTEXLOCKER>

bool QtlSmartPointer< T, MUTEXLOCKER >::operator!= ( const QtlSmartPointer< T, MUTEXLOCKER > & sp ) const

inline

Unequality operator.

Check if this smart pointer and the sp smart pointer point to different objects.

Caveat: Null pointers are not reliably compared with this operator. It shall not be used to compare against null pointer. Do not check != 0, use the method isNull() instead. Also, if both smart pointers are null pointers, the result is unpredictable, it can be true or false.

Parameters

[in] sp A smart pointer to compare with.

Returns: True if both smart pointers reference distinct objects and false otherwise.

◆ operator->()

template<typename T, class MUTEXLOCKER>

T* QtlSmartPointer< T, MUTEXLOCKER >::operator-> ( ) const

inline

Redirection operator.

With this operator, a smart pointer can be used in the same way as a standard pointer.

Example:

class Foo
{
public:
   void open();
};
QtlSmartPointer<Foo,QtlMutexLocker> ptr(new Foo());
ptr->open();

If this object is the null pointer, the operator returns zero and the further dereferencing operation will likely throw an exception.

Returns: A standard pointer T* to the pointed object or 0 if this object is the null pointer.

◆ operator*()

template<typename T, class MUTEXLOCKER>

T& QtlSmartPointer< T, MUTEXLOCKER >::operator* ( ) const

inline

Accessor operator.

With this operator, a smart pointer can be used in the same way as a standard pointer.

Example:

void f(Foo&);
QtlSmartPointer<Foo,QtlMutexLocker> ptr(new Foo());
f(*ptr);

If this object is the null pointer, the operator will likely throw an exception.

Returns: A reference T& to the pointed object.

◆ release()

template<typename T, class MUTEXLOCKER>

T* QtlSmartPointer< T, MUTEXLOCKER >::release ( )

inline

Release the pointed object from the smart pointer management.

The previously pointed object is not deallocated, its address is returned. All smart pointers which pointed to the object now point to 0 (null pointers).

Caveat: The previously pointed object will no longer be automatically deleted. The caller must explicitly delete it later using the returned pointer value.

Returns: A standard pointer T* to the previously pointed object. Return 0 if this object was the null pointer.

◆ reset()

template<typename T, class MUTEXLOCKER>

void QtlSmartPointer< T, MUTEXLOCKER >::reset ( T * p = 0 )

inline

Deallocate the previous pointed object and set the pointer to the new object.

All smart pointers which pointed to the same object now point to the new one. The previously pointed object is deleted using the operator delete.

The standard pointer p can be either 0 (null pointer) or the address of an unmanaged dynamically allocated object (i.e. which has been allocated using the operator new). In this case, unmanaged means that the object must not be already controlled by another set of smart pointers.

Parameters

[in] p A pointer to an object of class T.

◆ clear()

template<typename T, class MUTEXLOCKER>

void QtlSmartPointer< T, MUTEXLOCKER >::clear ( )

inline

Clear this instance of the smart pointer.

The referenced object is deallocated if no more reference exists. Then, this smart pointer becomes the null pointer. sp.clear() is equivalent to sp = (T*)(0).

◆ isNull()

template<typename T, class MUTEXLOCKER>

bool QtlSmartPointer< T, MUTEXLOCKER >::isNull ( ) const

inline

Check if this smart pointer is a null pointer.

Returns: True if this smart pointer is a null pointer, false otherwise.

◆ upcast()

template<typename T, class MUTEXLOCKER>

template<typename ST >

QtlSmartPointer<ST,MUTEXLOCKER> QtlSmartPointer< T, MUTEXLOCKER >::upcast ( )

inline

Upcast operation.

This method converts a smart pointer to an object of class T into a smart pointer to an object of a super-class ST of T.

If this object is not the null pointer, the ownership of the pointed object is transfered to a new smart pointer to ST. This new smart pointer is returned. This object (the smart pointer to T) and all other smart pointers to T which pointed to the same object become null pointers.

Template Parameters

ST	A super-class of T (immediate or indirect).

Returns: If this object is not the null pointer, return a smart pointer to the same object, interpreted as ST. Otherwise, return the null pointer. The MUTEXLOCKER type of the returned smart pointer is the same as used in this object.

◆ downcast()

template<typename T, class MUTEXLOCKER>

template<typename ST >

QtlSmartPointer<ST,MUTEXLOCKER> QtlSmartPointer< T, MUTEXLOCKER >::downcast ( )

inline

Downcast operation.

This method converts a smart pointer to an object of class T into a smart pointer to an object of a subclass ST of T. This operation is equivalent to a dynamic_cast operator on regular pointers.

If this object is not the null pointer and points to an instance of ST, the ownership of the pointed object is transfered to a new smart pointer to ST. This new smart pointer is returned. This object (the smart pointer to T) and all other smart pointers to T which pointed to the same object become null pointers.

If this object is the null pointer or points to a T object which is not an instance of ST, the returned value is the null pointer and this object is unmodified.

If RTTI is not supported, define the symbol QTL_NO_RTTI before including this header file. In that case, this method is equivalent to a static_cast. Warning: In this case, the transfer of ownership to the returned value is always performed. It is the responsibility of the application to ensure that the conversion is valid.

Template Parameters

ST	A subclass of T (immediate or indirect).

Returns: If this object is not the null pointer and points to an instance of ST, return a smart pointer to the same object, interpreted as ST. Otherwise, return the null pointer. The MUTEXLOCKER type of the returned smart pointer is the same as used in this object.

◆ changeMutex()

template<typename T, class MUTEXLOCKER>

template<typename NEWMUTEXLOCKER >

QtlSmartPointer<T,NEWMUTEXLOCKER> QtlSmartPointer< T, MUTEXLOCKER >::changeMutex ( )

inline

Change mutex locker type.

This method converts a smart pointer to an object of class T into a smart pointer to the same class T with a different class of mutex locker.

If this object is not the null pointer, the ownership of the pointed object is transfered to a new smart pointer. This new smart pointer is returned. This object and all other smart pointers of the same class which pointed to the same object become null pointers.

Template Parameters

NEWMUTEXLOCKER Another class which is used to synchronize access to the smart pointer internal state. Typically used to switch back and forth between QtlMutexLocker and QtlNullMutexLocker.

Returns: A smart pointer to the same object.

◆ pointer()

template<typename T, class MUTEXLOCKER>

T* QtlSmartPointer< T, MUTEXLOCKER >::pointer ( ) const

inline

Get a standard pointer T* on the pointed object.

Warning: This is an unchecked operation. Do not store this pointer to dereference it later since the pointed object may have been deleted in the meantime if no more smart pointer reference the object.

Returns: A standard pointer T* to the pointed object or 0 if this object is the null pointer.

◆ count()

template<typename T, class MUTEXLOCKER>

int QtlSmartPointer< T, MUTEXLOCKER >::count ( ) const

inline

Get the reference count value.

This is informational only. In multi-threaded environments, the actual reference count may change before the result is actually used.

Returns: The number of smart pointer objects which reference the same pointed object.

Member Data Documentation

◆ _shared

template<typename T, class MUTEXLOCKER>

SmartShared* QtlSmartPointer< T, MUTEXLOCKER >::_shared

private

QtlSmartPointer private field simply points to a SmartShared instance.

The documentation for this class was generated from the following files:

Classes

Public Member Functions

Private Attributes

Detailed Description

template<typename T, class MUTEXLOCKER> class QtlSmartPointer< T, MUTEXLOCKER >

Constructor & Destructor Documentation

◆ QtlSmartPointer() [1/2]

◆ QtlSmartPointer() [2/2]

◆ ~QtlSmartPointer()

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ operator!=()

◆ operator->()

◆ operator*()

◆ release()

◆ reset()

◆ clear()

◆ isNull()

◆ upcast()

◆ downcast()

◆ changeMutex()

◆ pointer()

◆ count()

Member Data Documentation

◆ _shared

template<typename T, class MUTEXLOCKER>
class QtlSmartPointer< T, MUTEXLOCKER >