Saf::Mem::SharedPtr< T > Class Template Reference

Shared pointer class with reference counting. More...

#include <SharedPtr.h>

List of all members.

Public Member Functions
	SharedPtr ()
	Default constructor.
	SharedPtr (T *ptr)
	Constructor that binds a given pointer.
	SharedPtr (const SharedPtr< T > &p)
	Copy constructor.
	~SharedPtr ()
	Destructor.
SharedPtr< T > &	Bind (T *ptr)
	Bind a given object pointer.
SharedPtr< T > &	BindWithCounter (T *ptr, Size *counter)
	Bind a given object pointer and an external reference counter.
template<class C >
SharedPtr< C >	Cast ()
	Dynamic cast to a different pointer type.
void	Free ()
	Explicitly unbind and free the attached object.
T *	Get ()
	Get a pointer to the binded object.
const T *	Get () const
	Get a pointer to the binded object.
bool	IsNull () const
	Returns true when there is no binded pointer.
T &	operator* ()
	Get a reference to the binded object.
const T &	operator* () const
	Get a reference to the binded object.
T *	operator-> ()
	Get a pointer to the binded object.
const T *	operator-> () const
	Get a pointer to the binded object.
SharedPtr< T > &	operator= (const SharedPtr< T > &p)
	Assignment operator.
void	Swap (SharedPtr< T > &p)
	Swap two shared pointers.

---

Detailed Description

template<class T>
class Saf::Mem::SharedPtr< T >

Shared pointer class with reference counting.

       Use this class instead of standard pointers to obtain
       an exception safe pointer class with automatic deallocation
       and reference counting. Examples:

                // The memory will be freed automatically when p is destroyed
                Saf::SharedPtr<int> p(SAF_NEW int);

                // The memory will be freed automatically when BOTH p and q are destroyed
                Saf::SharedPtr<int> p(SAF_NEW int), q;
                q = p;

                // Another example with type casting
                Saf::SharedPtr<A> p(SAF_NEW A);
                Saf::SharedPtr<B> q = p.template Cast<B>(); // Type cast, works if class A is derived from class B
                p.Free(); // Unbind, the memory is not deallocated as it is still referenced by q
                q.Free(); // Unbind, the memory is deallocated now

Because of the reference counting the Saf::SharedPtr object can be safely returned from functions, used in collections, etc. However, be careful in the following situations:

• When object or its member hold a Saf::SharedPtr to itself. In this situation a cycle in the references may appear and the memory will not be freed.
• Better avoid unnamed temporary Saf::SharedPtr objects in function arguments. For instance in this code:

                  func(Saf::SharedPtr<A>(SAF_NEW A()), SomeFunc());
  

  Because function arguments are evaluated in unspecified order it may happen that exception is thrown by SomeFunc after the allocation of A() and before the constructor of Saf::SharedPtr and thus creating a dangling pointer.

Warning:

Do not use with array pointers! Use Saf::Collection::Array class instead.

---

Constructor & Destructor Documentation

template<class T>

Saf::Mem::SharedPtr< T >::SharedPtr

(

)

[inline]

Default constructor.

template<class T>

Saf::Mem::SharedPtr< T >::SharedPtr

(

T *

ptr

)

[inline, explicit]

Constructor that binds a given pointer.

This constructor is explicit to prevent dangerous automatic conversions of pointers to Saf::SharedPtr.

template<class T>

Saf::Mem::SharedPtr< T >::SharedPtr

(

const SharedPtr< T > &

p

)

[inline]

Copy constructor.

template<class T>

Saf::Mem::SharedPtr< T >::~SharedPtr

(

)

[inline]

Destructor.

---

Member Function Documentation

template<class T>

SharedPtr<T>& Saf::Mem::SharedPtr< T >::Bind

(

T *

ptr

)

[inline]

Bind a given object pointer.

           When the pointer is binded it becomes reference counted and is freed
           when the last reference disappears. Do not bind the same pointer to
           several Saf::SharedPtr objects, use copy constructor or assignment operator
           instead. Example:

                int *a = SAF_NEW int(5);
                Saf::SharedPtr<int> p(a), q(a); // Wrong, p and q do not know of each other, memory will be deallocated twice!
                Saf::SharedPtr<int> p(a), q(p); // Correct
                Saf::SharedPtr<int> p(a), q = p; // Correct

template<class T>

SharedPtr<T>& Saf::Mem::SharedPtr< T >::BindWithCounter	(	T *	ptr,
		Size *	counter
	)		[inline]

Bind a given object pointer and an external reference counter.

Warning:

This method is intended for internal purposes. Do not use it unless you really know what you are doing.

See also:

Bind().

template<class T>

template<class C >

SharedPtr<C> Saf::Mem::SharedPtr< T >::Cast

(

)

[inline]

Dynamic cast to a different pointer type.

Can be used to safely cast the attached pointer to a different type (e.g., to a base class) without affecting the reference counting.

template<class T>

void Saf::Mem::SharedPtr< T >::Free

(

)

[inline]

Explicitly unbind and free the attached object.

Keep in mind that the binded pointer is actually freed from the memory only when there are no other references to it.

template<class T>

T* Saf::Mem::SharedPtr< T >::Get

(

)

[inline]

Get a pointer to the binded object.

template<class T>

const T* Saf::Mem::SharedPtr< T >::Get

(

)

const [inline]

Get a pointer to the binded object.

template<class T>

bool Saf::Mem::SharedPtr< T >::IsNull

(

)

const [inline]

Returns true when there is no binded pointer.

template<class T>

T& Saf::Mem::SharedPtr< T >::operator*

(

)

[inline]

Get a reference to the binded object.

template<class T>

const T& Saf::Mem::SharedPtr< T >::operator*

(

)

const [inline]

Get a reference to the binded object.

template<class T>

T* Saf::Mem::SharedPtr< T >::operator->

(

)

[inline]

Get a pointer to the binded object.

template<class T>

const T* Saf::Mem::SharedPtr< T >::operator->

(

)

const [inline]

Get a pointer to the binded object.

template<class T>

SharedPtr<T>& Saf::Mem::SharedPtr< T >::operator=

(

const SharedPtr< T > &

p

)

[inline]

Assignment operator.

template<class T>

void Saf::Mem::SharedPtr< T >::Swap

(

SharedPtr< T > &

p

)

[inline]

Swap two shared pointers.

---

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

• Saf/Mem/SharedPtr.h