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

Public Types
typedef T	DataType
	Generic definition of the pointed type for this safe pointer.

typedef MUTEX	MutexType
	Generic definition of the mutex for this safe pointer.

Public Member Functions
	SafePtr (const SafePtr< T, MUTEX > &sp)
	Copy constructor. More...

	SafePtr (SafePtr< T, MUTEX > &&sp) noexcept
	Move constructor. More...

	SafePtr (T *p=nullptr)
	Default constructor using an optional unmanaged object. More...

	~SafePtr ()
	Destructor. More...

template<typename NEWMUTEX >
SafePtr< T, NEWMUTEX >	changeMutex ()
	Change mutex type. More...

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

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

template<typename ST , typename std::enable_if< std::is_base_of< T, ST >::value >::type * = nullptr>
SafePtr< ST, MUTEX >	downcast ()
	Downcast operation. More...

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

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

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

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

SafePtr< T, MUTEX > &	operator= (const SafePtr< T, MUTEX > &sp)
	Assignment between safe pointers. More...

SafePtr< T, MUTEX > &	operator= (SafePtr< T, MUTEX > &&sp) noexcept
	Move assignment between safe pointers. More...

SafePtr< T, MUTEX > &	operator= (T *p)
	Assignment from a standard pointer `T*`. More...

bool	operator== (const SafePtr< T, MUTEX > &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 safe pointer management. More...

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

template<typename ST , typename std::enable_if< std::is_base_of< ST, T >::value >::type * = nullptr>
SafePtr< ST, MUTEX >	upcast ()
	Upcast operation. More...

Detailed Description

template<typename T, class MUTEX = NullMutex>
class ts::SafePtr< T, MUTEX >

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

The ts::SafePtr template class is an implementation of the safe pointer design pattern. A safe pointer implements the semantics of a standard pointer with automatic memory management.

Safe 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 safe 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, safe 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 safe pointers (assignment, comparison, dereferencing, etc.)

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

The ts::SafePtr template class can be made thread-safe using a mutex. The type of mutex to use is given by the template parameter MUTEX which must be a subclass of ts::MutexInterface. By default, ts::NullMutex is used. The default implementation is consequently not thread-safe but there is no synchronization overhead. To use safe pointers in a multi-thread environment, specify an actual mutex implementation for the target environment.

Template Parameters

T	The type of the pointed object. Cannot be an array type.
MUTEX	A subclass of ts::MutexInterface which is used to synchronize access to the safe pointer internal state.

Constructor & Destructor Documentation

◆ SafePtr() [1/3]

template<typename T , class MUTEX = NullMutex>

ts::SafePtr< T, MUTEX >::SafePtr ( T * p = nullptr )

inline

Default constructor using an optional unmanaged object.

The optional argument p can be either nullptr 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 safe pointers.

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

Example:

ts::SafePtr<Foo> ptr(new Foo(...));

Parameters

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

Exceptions

std::bad_alloc Thrown if insufficient memory is available for internal safe pointer management.

◆ SafePtr() [2/3]

template<typename T , class MUTEX = NullMutex>

ts::SafePtr< T, MUTEX >::SafePtr ( const SafePtr< T, MUTEX > & 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 safe pointer instance.

◆ SafePtr() [3/3]

template<typename T , class MUTEX = NullMutex>

ts::SafePtr< T, MUTEX >::SafePtr ( SafePtr< T, MUTEX > && sp )

inlinenoexcept

Move constructor.

Parameters

[in,out] sp Another safe pointer instance.

◆ ~SafePtr()

template<typename T , class MUTEX = NullMutex>

ts::SafePtr< T, MUTEX >::~SafePtr ( )

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/3]

template<typename T , class MUTEX = NullMutex>

SafePtr<T,MUTEX>& ts::SafePtr< T, MUTEX >::operator= ( const SafePtr< T, MUTEX > & sp )

Assignment between safe 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/3]

template<typename T , class MUTEX = NullMutex>

SafePtr<T,MUTEX>& ts::SafePtr< T, MUTEX >::operator= ( SafePtr< T, MUTEX > && sp )

noexcept

Move assignment between safe pointers.

Parameters

[in,out] sp The value to assign.

Returns: A reference to this object.

◆ operator=() [3/3]

template<typename T , class MUTEX = NullMutex>

SafePtr<T,MUTEX>& ts::SafePtr< T, MUTEX >::operator= ( T * p )

Assignment from a standard pointer T*.

The pointed T object becomes managed by this safe pointer.

The standard pointer p can be either nullptr 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 safe pointers.

After the assignment, this object references the T object. If this safe 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.

Exceptions

std::bad_alloc Thrown if insufficient memory is available for internal safe pointer management.

◆ operator==()

template<typename T , class MUTEX = NullMutex>

bool ts::SafePtr< T, MUTEX >::operator== ( const SafePtr< T, MUTEX > & sp ) const

inline

Equality operator.

Check if this safe pointer and the sp safe 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 == nullptr, use the method isNull() instead. Also, if both safe pointers are null pointers, the result is unpredictable, it can be true or false.

Parameters

[in] sp A safe pointer to compare with.

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

◆ operator!=()

template<typename T , class MUTEX = NullMutex>

bool ts::SafePtr< T, MUTEX >::operator!= ( const SafePtr< T, MUTEX > & sp ) const

inline

Unequality operator.

Check if this safe pointer and the sp safe 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 != nullptr, use the method isNull() instead. Also, if both safe pointers are null pointers, the result is unpredictable, it can be true or false.

Parameters

[in] sp A safe pointer to compare with.

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

◆ operator->()

template<typename T , class MUTEX = NullMutex>

T* ts::SafePtr< T, MUTEX >::operator-> ( ) const

inline

Redirection operator.

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

Example:

class Foo
{
public:
    void open();
};
 
ts::SafePtr<Foo> 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 nullptr if this object is the null pointer.

◆ operator*()

template<typename T , class MUTEX = NullMutex>

T& ts::SafePtr< T, MUTEX >::operator* ( ) const

inline

Accessor operator.

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

Example:

void f(Foo&);
 
ts::SafePtr<Foo> 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 MUTEX = NullMutex>

T* ts::SafePtr< T, MUTEX >::release ( )

inline

Release the pointed object from the safe pointer management.

The previously pointed object is not deallocated, its address is returned. All safe pointers which pointed to the object now point to nullptr.

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 nullptr if this object was the null pointer.

◆ reset()

template<typename T , class MUTEX = NullMutex>

void ts::SafePtr< T, MUTEX >::reset ( T * p = nullptr )

inline

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

All safe 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 nullptr 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 safe pointers.

Parameters

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

◆ clear()

template<typename T , class MUTEX = NullMutex>

void ts::SafePtr< T, MUTEX >::clear ( )

inline

Clear this instance of the safe pointer.

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

Exceptions

std::bad_alloc Thrown if insufficient memory is available for internal safe pointer management.

◆ isNull()

template<typename T , class MUTEX = NullMutex>

bool ts::SafePtr< T, MUTEX >::isNull ( ) const

inline

Check if this safe pointer is a null pointer.

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

◆ upcast()

template<typename T , class MUTEX = NullMutex>

template<typename ST , typename std::enable_if< std::is_base_of< ST, T >::value >::type * = nullptr>

SafePtr<ST,MUTEX> ts::SafePtr< T, MUTEX >::upcast ( )

inline

Upcast operation.

This method converts a safe pointer to an object of class T into a safe 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 safe pointer to ST. This new safe pointer is returned. This object (the safe pointer to T) and all other safe 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 safe pointer to the same object, interpreted as ST. Otherwise, return the null pointer. The MUTEX type of the returned safe pointer is the same as used in this object.

◆ downcast()

template<typename T , class MUTEX = NullMutex>

template<typename ST , typename std::enable_if< std::is_base_of< T, ST >::value >::type * = nullptr>

SafePtr<ST,MUTEX> ts::SafePtr< T, MUTEX >::downcast ( )

inline

Downcast operation.

This method converts a safe pointer to an object of class T into a safe 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 safe pointer to ST. This new safe pointer is returned. This object (the safe pointer to T) and all other safe 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.

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 safe pointer to the same object, interpreted as ST. Otherwise, return the null pointer. The MUTEX type of the returned safe pointer is the same as used in this object.

◆ changeMutex()

template<typename T , class MUTEX = NullMutex>

template<typename NEWMUTEX >

SafePtr<T,NEWMUTEX> ts::SafePtr< T, MUTEX >::changeMutex ( )

inline

Change mutex type.

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

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

Template Parameters

NEWMUTEX Another subclass of ts::MutexInterface which is used to synchronize access to the new safe pointer internal state.

Returns: A safe pointer to the same object.

◆ pointer()

template<typename T , class MUTEX = NullMutex>

T* ts::SafePtr< T, MUTEX >::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 safe pointer reference the object.

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

◆ count()

template<typename T , class MUTEX = NullMutex>

int ts::SafePtr< T, MUTEX >::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 safe pointer objects which reference the same pointed object.

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

tsSafePtr.h

Public Types

Public Member Functions

Detailed Description

template<typename T, class MUTEX = NullMutex> class ts::SafePtr< T, MUTEX >

Constructor & Destructor Documentation

◆ SafePtr() [1/3]

◆ SafePtr() [2/3]

◆ SafePtr() [3/3]

◆ ~SafePtr()

Member Function Documentation

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator==()

◆ operator!=()

◆ operator->()

◆ operator*()

◆ release()

◆ reset()

◆ clear()

◆ isNull()

◆ upcast()

◆ downcast()

◆ changeMutex()

◆ pointer()

◆ count()

template<typename T, class MUTEX = NullMutex>
class ts::SafePtr< T, MUTEX >