MySQL++: mysqlpp::RefCountedPointer< T, Destroyer > Class Template Reference
mysqlpp::RefCountedPointer< T, Destroyer > Class Template Reference

Creates an object that acts as a reference-counted pointer to another object. More...

`#include <refcounted.h>`

Inheritance diagram for mysqlpp::RefCountedPointer< T, Destroyer >:
[legend]

## Public Types

typedef RefCountedPointer< T > | ThisType
| alias for this object's type

## Public Member Functions

| RefCountedPointer ()
| Default constructor. More...
| RefCountedPointer (T *c)
| Standard constructor. More...
| RefCountedPointer (const ThisType &other)
| Copy constructor.
| ~RefCountedPointer ()
| Destructor. More...
ThisType & | assign (T *c)
| Sets (or resets) the pointer to the counted object. More...
ThisType & | assign (const ThisType &other)
| Copy an existing refcounted pointer. More...
ThisType & | operator= (T *c)
| Set (or reset) the pointer to the counted object. More...
ThisType & | operator= (const ThisType &rhs)
| Copy an existing refcounted pointer. More...
T * | operator-> () const
| Access the object through the smart pointer.
T & | operator* () const
| Dereference the smart pointer.
| operator void * ()
| Returns the internal raw pointer converted to void*. More...
| operator const void * () const
| Returns the internal raw pointer converted to const void*. More...
T * | raw ()
| Return the raw pointer in T* context.
const T * | raw () const
| Return the raw pointer when used in const T* context.
void | swap (ThisType &other)
| Exchange our managed memory with another pointer.

## Detailed Description

### template<class T, class Destroyer = RefCountedPointerDestroyer<T>>
class mysqlpp::RefCountedPointer< T, Destroyer >

Creates an object that acts as a reference-counted pointer to another object.

Resulting type acts like a pointer in all respects, except that it manages the memory it points to by observing how many users there are for the object.

This attempts to be as automatic as reference counting in a programming language with memory management. Like all automatic memory management schemes, it has penalties: it turns the single indirection of an unmanaged pointer into a double indirection, and has additional management overhead in the assignment operators due to the reference counter. This is an acceptable tradeoff when wrapping objects that are expensive to copy, and which need to be "owned" by disparate parties: you can allocate the object just once, then pass around the reference counted pointer, knowing that the last user will "turn out the lights".

Implementation detail: You may notice that this class manages two pointers, one to the data we're managing, and one to the reference count. You might wonder why we don't wrap these up into a structure and keep just a pointer to an instance of it to simplify the memory management. It would indeed do that, but then every access to the data we manage would be a triple indirection instead of just double. It's a tradeoff, and we've chosen to take a minor complexity hit to avoid the performance hit.

## Constructor & Destructor Documentation

## RefCountedPointer() [1/2]

template<class T , class Destroyer = RefCountedPointerDestroyer<T>>

mysqlpp::RefCountedPointer< T, Destroyer >::RefCountedPointer | ( |  | ) |

inline

Default constructor.

An object constructed this way is useless until you vivify it with operator =() or assign().

## RefCountedPointer() [2/2]

template<class T , class Destroyer = RefCountedPointerDestroyer<T>>

mysqlpp::RefCountedPointer< T, Destroyer >::RefCountedPointer | ( | T * | c | ) |

inline explicit

Standard constructor.

Parameters

  c | A pointer to the object to be managed. If you pass 0, it's like calling the default ctor instead, only more work: the object's useless until you vivify it with operator =() or assign().

## ~RefCountedPointer()

template<class T , class Destroyer = RefCountedPointerDestroyer<T>>

mysqlpp::RefCountedPointer< T, Destroyer >::~RefCountedPointer | ( |  | ) |

inline

Destructor.

This only destroys the managed memory if the reference count drops to 0.

## Member Function Documentation

## assign() [1/2]

template<class T , class Destroyer = RefCountedPointerDestroyer<T>>

ThisType& mysqlpp::RefCountedPointer< T, Destroyer >::assign | ( | const ThisType & | other | ) |

inline

Copy an existing refcounted pointer.

If we are managing a pointer, this decrements the refcount for it and destroys the managed object if the refcount falls to 0. Then we increment the other object's reference count and copy that refcount and the managed pointer into this object.

This is a no-op if you pass a reference to this same object.

## assign() [2/2]

template<class T , class Destroyer = RefCountedPointerDestroyer<T>>

ThisType& mysqlpp::RefCountedPointer< T, Destroyer >::assign | ( | T * | c | ) |

inline

Sets (or resets) the pointer to the counted object.

If we are managing a pointer, this decrements the refcount for it and destroys the managed object if the refcount falls to 0.

This is a no-op if you pass the same pointer we're already managing.

Referenced by mysqlpp::RefCountedPointer< T, Destroyer >::operator=().

## operator const void *()

template<class T , class Destroyer = RefCountedPointerDestroyer<T>>

mysqlpp::RefCountedPointer< T, Destroyer >::operator const void * | ( |  | ) | const

inline

Returns the internal raw pointer converted to const void*.

See also
  comments for operator void*()

## operator void *()

template<class T , class Destroyer = RefCountedPointerDestroyer<T>>

mysqlpp::RefCountedPointer< T, Destroyer >::operator void * | ( |  | ) |

inline

Returns the internal raw pointer converted to void*.

This isn't intended to be used directly; if you need the pointer, call raw() instead. It's used internally by the compiler to implement operators bool, ==, and !=

WARNING: This makes it possible to say

RefCountedPointer<Foo> bar(new Foo);
delete bar;

This will almost kinda sorta do the right thing: the Foo object held by the refcounted pointer will be destroyed as you wanted, but then when the refcounted pointer goes out of scope, the memory is deleted a second time, which will probably crash your program. This is easy to accidentally do when converting a good ol' unmanaged pointer to a refcounted pointer and forgetting to remove the delete calls needed previously.

## operator=() [1/2]

template<class T , class Destroyer = RefCountedPointerDestroyer<T>>

ThisType& mysqlpp::RefCountedPointer< T, Destroyer >::operator= | ( | const ThisType & | rhs | ) |

inline

Copy an existing refcounted pointer.

This is essentially the same thing as assign(const ThisType&). The choice between the two is just a matter of syntactic preference.

References mysqlpp::RefCountedPointer< T, Destroyer >::assign().

## operator=() [2/2]

template<class T , class Destroyer = RefCountedPointerDestroyer<T>>

ThisType& mysqlpp::RefCountedPointer< T, Destroyer >::operator= | ( | T * | c | ) |

inline

Set (or reset) the pointer to the counted object.

This is essentially the same thing as assign(T*). The choice between the two is just a matter of syntactic preference.

References mysqlpp::RefCountedPointer< T, Destroyer >::assign().

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

- refcounted.h