Cgu::SharedPtr< T > Class Template Reference

This is a smart pointer for managing the lifetime of objects allocated on freestore. More...

#include <c++-gtk-utils/shared_ptr.h>

Public Member Functions
	SharedPtr (T *ptr=0)
	SharedPtr (T *ptr, Cgu::SharedPtrAllocFail::Leave tag)
void	reset (T *ptr=0)
void	reset (T *ptr, Cgu::SharedPtrAllocFail::Leave tag)
	SharedPtr (const SharedPtr &sh_ptr)
template<class U >
	SharedPtr (const SharedPtr< U > &sh_ptr)
SharedPtr &	operator= (SharedPtr sh_ptr)
template<class U >
SharedPtr &	operator= (const SharedPtr< U > &sh_ptr)
T *	get () const
T &	operator* () const
T *	operator-> () const
unsigned int	get_refcount () const
	~SharedPtr ()

Friends
template<class U >
class	SharedPtr

Detailed Description

template<class T>
class Cgu::SharedPtr< T >

This is a smart pointer for managing the lifetime of objects allocated on freestore.

See also

SharedLockPtr SharedPtrError

This is a smart pointer for managing the lifetime of objects allocated on freestore with the new expression. A managed object will be deleted when the last SharedPtr referencing it is destroyed.

From version 1.2.12, the library provides ==, != and < comparison operators for SharedPtr, but only if the library is compiled with the --with-smart-ptr-comp option, or if the user code defines the symbol CGU_USE_SMART_PTR_COMPARISON before shared_ptr.h is first parsed. This is because, if user code has provided such operators for these smart pointers itself, a duplicated function definition would arise.

If the library is compiled with the --with-glib-memory-slices-no-compat configuration option, Cgu::SharedPtr constructs its reference counting internals using glib memory slices. Although it is safe in a multi-threaded program if glib < 2.32 is installed to construct a static SharedPtr object in global namespace (that is, prior to g_thread_init() being called) by means of the default constructor and/or a pointer argument of NULL, it is not safe if constructed with a non-NULL pointer value. If glib >= 2.32 is installed, global objects with memory slices are safe in all circumstances. (Having said that, it would be highly unusual to have global SharedPtr objects.)

Constructor & Destructor Documentation

SharedPtr() [1/4]

template<class T >

Cgu::SharedPtr< T >::SharedPtr ( T *  ptr = 0 )

inlineexplicit

Constructor taking an unmanaged object.

Parameters

ptr	The object which the SharedPtr is to manage (if any).

Exceptions

std::bad_alloc

This constructor will not throw if the 'ptr' argument has a NULL value (the default), otherwise it might throw std::bad_alloc if memory is exhausted and the system throws in that case. If such an exception is thrown, this constructor is exception safe (it does not leak resources), but as well as cleaning itself up this constructor will also delete the managed object passed to it to avoid a memory leak. If such automatic deletion is not wanted in that case, use the version of this constructor taking a Cgu::SharedPtrAllocFail::Leave tag argument.

Note

std::bad_alloc will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system.

SharedPtr() [2/4]

template<class T >

Cgu::SharedPtr< T >::SharedPtr ( T *  ptr, Cgu::SharedPtrAllocFail::Leave  tag  )

inline

Constructor taking an unmanaged object.

Parameters

ptr	The object which the SharedPtr is to manage.
tag	Passing the tag emumerator Cgu::SharedPtrAllocFail::leave causes this constructor not to delete the new managed object passed as the 'ptr' argument in the event of internal allocation in this method failing because of memory exhaustion (in that event, Cgu::SharedPtrError will be thrown).

Exceptions

Cgu::SharedPtrError

This constructor might throw Cgu::SharedPtrError if memory is exhausted and the system would otherwise throw std::bad_alloc in that case. This constructor is exception safe (it does not leak resources), and if such an exception is thrown it will clean itself up, but it will not attempt to delete the new managed object passed to it. Access to the object passed to the 'ptr' argument can be obtained via the thrown Cgu::SharedPtrError object.

Note

1. On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, so in those cases this version of the constructor will not be useful.

2. If the library has been installed using the --with-glib-memory-slices-no-compat configuration option this version of the constructor will also not be useful: instead glib will terminate the program if it is unable to obtain memory from the operating system.

Since 0.9.1

SharedPtr() [3/4]

template<class T >

Cgu::SharedPtr< T >::SharedPtr ( const SharedPtr< T > &  sh_ptr )

inline

This copy constructor does not throw.

Parameters

sh_ptr

The shared pointer to be copied.

SharedPtr() [4/4]

template<class T >

template<class U >

Cgu::SharedPtr< T >::SharedPtr ( const SharedPtr< U > &  sh_ptr )

inline

A version of the copy constructor which enables pointer type conversion (assuming the type passed is implicitly type convertible to the managed type, such as a derived type). This copy constructor does not throw.

Parameters

sh_ptr

The shared pointer to be copied.

~SharedPtr()

template<class T >

Cgu::SharedPtr< T >::~SharedPtr ( )

inline

The destructor does not throw unless the destructor of a managed object throws - that should never happen.

Member Function Documentation

get()

template<class T >

T* Cgu::SharedPtr< T >::get ( ) const

inline

This method does not throw.

Returns

A pointer to the managed object (or NULL if none is managed).

get_refcount()

template<class T >

unsigned int Cgu::SharedPtr< T >::get_refcount ( ) const

inline

This method does not throw.

Returns

The number of SharedPtr objects referencing the managed object (or 0 if none is managed by this SharedPtr).

operator*()

template<class T >

T& Cgu::SharedPtr< T >::operator* ( ) const

inline

This method does not throw.

Returns

A reference to the managed object.

operator->()

template<class T >

T* Cgu::SharedPtr< T >::operator-> ( ) const

inline

This method does not throw.

Returns

A pointer to the managed object (or NULL if none is managed).

operator=() [1/2]

template<class T >

template<class U >

SharedPtr& Cgu::SharedPtr< T >::operator= ( const SharedPtr< U > &  sh_ptr )

inline

A version of the assignment operator which enables pointer type conversion (assuming the type passed is implicitly type convertible to the managed type, such as a derived type). This method does not throw unless the destructor of a managed object throws.

Parameters

sh_ptr

the assignor.

Returns

The SharedPtr object after assignment.

operator=() [2/2]

template<class T >

SharedPtr& Cgu::SharedPtr< T >::operator= ( SharedPtr< T >  sh_ptr )

inline

This method does not throw unless the destructor of a managed object throws.

Parameters

sh_ptr

the assignor.

Returns

The SharedPtr object after assignment.

reset() [1/2]

template<class T >

void Cgu::SharedPtr< T >::reset ( T *  ptr, Cgu::SharedPtrAllocFail::Leave  tag  )

inline

Causes the SharedPtr to cease to manage its managed object (if any), deleting it if this is the last SharedPtr object managing it. The SharedPtr object will manage the new object passed (which must not be managed by any other SharedPtr object). This method is exception safe, but see the comments below on Cgu::SharedPtrError.

Parameters

ptr	A new unmanaged object to manage (if no new object is to be managed, use the version of reset() taking a default value of NULL).
tag	Passing the tag emumerator Cgu::SharedPtrAllocFail::leave causes this method not to delete the new managed object passed as the 'ptr' argument in the event of internal allocation in this method failing because of memory exhaustion (in that event, Cgu::SharedPtrError will be thrown).

Exceptions

Cgu::SharedPtrError

This method might throw Cgu::SharedPtrError if memory is exhausted and the system would otherwise throw std::bad_alloc in that case. Note that if such an exception is thrown then this method will do nothing (it is strongly exception safe and will continue to manage the object it was managing prior to the call), and it will not attempt to delete the new managed object passed to it. Access to the object passed to the 'ptr' argument can be obtained via the thrown Cgu::SharedPtrError object.

Note

1. On systems with over-commit/lazy-commit combined with virtual memory (swap), it is rarely useful to check for memory exhaustion, so in those cases this version of the reset() method will not be useful.

2. If the library has been installed using the --with-glib-memory-slices-no-compat configuration option this version of the reset() method will also not be useful: instead glib will terminate the program if it is unable to obtain memory from the operating system.

Since 0.9.1

reset() [2/2]

template<class T >

void Cgu::SharedPtr< T >::reset ( T *  ptr = 0 )

inline

Causes the SharedPtr to cease to manage its managed object (if any), deleting it if this is the last SharedPtr object managing it. If the argument passed is not NULL, the SharedPtr object will manage the new object passed (which must not be managed by any other SharedPtr object). This method is exception safe, but see the comments below on std::bad_alloc.

Parameters

ptr	NULL (the default), or a new unmanaged object to manage.

Exceptions

std::bad_alloc

This method will not throw if the 'ptr' argument has a NULL value (the default) and the destructor of a managed object does not throw, otherwise it might throw std::bad_alloc if memory is exhausted and the system throws in that case. Note that if such an exception is thrown then this method will do nothing (it is strongly exception safe and will continue to manage the object it was managing prior to the call), except that it will delete the new managed object passed to it to avoid a memory leak. If such automatic deletion in the event of such an exception is not wanted, use the reset() method taking a Cgu::SharedPtrAllocFail::Leave tag type as its second argument.

Note

std::bad_alloc will not be thrown if the library has been installed using the --with-glib-memory-slices-no-compat configuration option: instead glib will terminate the program if it is unable to obtain memory from the operating system.

Since 0.9.1

Friends And Related Function Documentation

SharedPtr

template<class T >

template<class U >

friend class SharedPtr

friend

---

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

• shared_ptr.h