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... | |
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.
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). |
|
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:
[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. |
|
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.
[in] | sp | Another smart pointer instance. |
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.
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.
[in] | sp | The value to assign. |
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.
[in] | p | A pointer to an object of class T. |
|
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.
[in] | sp | A smart pointer to compare with. |
|
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.
[in] | sp | A smart pointer to compare with. |
|
inline |
Redirection operator.
With this operator, a smart pointer can be used in the same way as a standard pointer.
Example:
If this object is the null pointer, the operator returns zero and the further dereferencing operation will likely throw an exception.
T*
to the pointed object or 0
if this object is the null pointer.
|
inline |
Accessor operator.
With this operator, a smart pointer can be used in the same way as a standard pointer.
Example:
If this object is the null pointer, the operator will likely throw an exception.
T&
to the pointed object.
|
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.
T*
to the previously pointed object. Return 0
if this object was the null pointer.
|
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.
[in] | p | A pointer to an object of class T. |
|
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)
.
|
inline |
Check if this smart pointer is a null pointer.
|
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.
ST | A super-class of T (immediate or indirect). |
|
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.
ST | A subclass of T (immediate or indirect). |
|
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.
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. |
|
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.
T*
to the pointed object or 0
if this object is the null pointer.
|
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.
|
private |
QtlSmartPointer private field simply points to a SmartShared instance.