regina::SafePtr< T > Class Template Reference

A reference counted smart pointer that supports alternate models of ownership. More...

`#include <utilities/safeptr.h>`

## Public Types

typedef T | element_type
| The pointee type. More...

## Public Member Functions

| SafePtr ()
| Constructs a new null pointer. More...
| SafePtr (T *object)
| Constructs a new safe pointer that points to the given object. More...
template<class Y >
| SafePtr (const SafePtr< Y > &other)
| Copy constructor. More...
T * | get () const
| Returns a raw pointer to the pointee, or `null` if the pointee has already been destroyed. More...
| operator bool () const
| Returns `true` if the pointee is non-null and has not yet been destroyed. More...
void | reset (T *object=0)
| Resets this to point to the given object. More...
SafePtr< T > & | operator= (const SafePtr< T > &)=delete
| Disable the default assignment operator. More...

## Detailed Description

### template<class T>
class regina::SafePtr< T >

A reference counted smart pointer that supports alternate models of ownership.

Specifically, there are two models of ownership for the pointee (of type T):

1. The pointee may be owned by the smart pointer(s), in which case it will be destroyed when the last smart pointer to it is destroyed.
2. Alternatively, the pointee may be owned by some other C++ object not using this smart pointer class. In this case, even when the last smart point to it is destroyed, the pointee itself will not be destroyed.

The pointee can indicate at runtime which model of ownership is in effect, through the return value of the function T::hasOwner().

The requirements for the pointee type T are as follows:

- T must subclass from `SafePointeeBase<T>`.
- T must implement a member function `bool hasOwner()`, which returns `true` if and only if some other C++ object (which is not a SafePtr) owns the pointee.

Destruction works as follows:

- If a pointee's destructor is called, all SafePtr pointers that point to it will become expired. These SafePtr pointers are still safe to use, but get() will return `null`.
- If a pointee has one or more SafePtr pointers to it, then when the last of these safe pointers is destroyed, the pointee itself will be destroyed if and only if the pointee's hasOwner() returns `false`.

Under the hood, SafePtr uses SafeRemnant to achieve this.

Author
  Matthias Goerner

## Member Typedef Documentation

## element_type

template<class T >

typedef T regina::SafePtr< T >::element_type

The pointee type.

This typedef is used by the boost infrastructure.

## Constructor & Destructor Documentation

## SafePtr() [1/3]

template<class T >

regina::SafePtr< T >::SafePtr | ( |  | ) |

inline

Constructs a new null pointer.

## SafePtr() [2/3]

template<class T >

regina::SafePtr< T >::SafePtr | ( | T * | object | ) |

inline

Constructs a new safe pointer that points to the given object.

Parameters

  object | the pointee. This may be `null`.

## SafePtr() [3/3]

template<class T >
template<class Y >

regina::SafePtr< T >::SafePtr | ( | const SafePtr< Y > & | other | ) |

inline

Copy constructor.

This constructor can also be used to cast a SafePtr for a derived class Y to a SafePtr for a base class T.

Precondition
  the class T (whose constructor is called) is a base class of Y.

Parameters

  other | the pointer to copy.

## Member Function Documentation

## get()

template<class T >

T * regina::SafePtr< T >::get | ( |  | ) | const

inline

Returns a raw pointer to the pointee, or `null` if the pointee has already been destroyed.

Returns
  the pointee.

## operator bool()

template<class T >

regina::SafePtr< T >::operator bool | ( |  | ) | const

inline

Returns `true` if the pointee is non-null and has not yet been destroyed.

This is equivalent to testing whether get() is not `null`.

Returns
  `true` if and only if the pointee is non-null and has not yet been destroyed.

## operator=()

template<class T >

SafePtr<T>& regina::SafePtr< T >::operator= | ( | const SafePtr< T > & |  | ) |

delete

Disable the default assignment operator.

## reset()

template<class T >

void regina::SafePtr< T >::reset | ( | T * | object = `0` | ) |

inline

Resets this to point to the given object.

This behaves in a similar manner to destroying the old safe pointer and constructing a new one: in particular, the old pointee may be destroyed if it meets the conditions outlined in the class notes above.

Parameters

  object | the new pointee. This may be `null`.

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

- utilities/safeptr.h

Copyright © 1999-2016, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).