regina::SnapshotRef< T > Class Template Reference

A reference to an image of type T that has been snapshotted at a particular moment in time. More...

#include <utilities/snapshot.h>

Public Member Functions
	SnapshotRef (const T &src)
	< The snapshot that we are referencing. More...
	SnapshotRef (const SnapshotRef &src)
	Creates a new copy of the given snapshot reference. More...
	SnapshotRef (SnapshotRef &&src) noexcept
	Moves the given snapshot reference into this new reference. More...
	~SnapshotRef ()
	Destroys this snapshot reference. More...
SnapshotRef &	operator= (const T &src)
	Sets this to be a snapshot of the given object in its current state. More...
SnapshotRef &	operator= (const SnapshotRef &src)
	Sets this to be a copy of the given snapshot reference. More...
SnapshotRef &	operator= (SnapshotRef &&src) noexcept
	Moves the given snapshot reference into this new reference. More...
void	swap (SnapshotRef &other) noexcept
	Swaps this and the given reference so that they refer to each others' snapshots. More...
bool	operator== (const SnapshotRef &rhs) const
	Tests whether this and the given snapshot reference refer to the same snapshot of the same type T object. More...
bool	operator!= (const SnapshotRef &rhs) const
	Tests whether this and the given snapshot reference do not refer to the same snapshot of the same type T object. More...
const T &	operator* () const
	Gives read-only access to the image that was snapshotted. More...
const T *	operator-> () const
	Gives read-only access to the image that was snapshotted. More...

Detailed Description

template<class T>
class regina::SnapshotRef< T >

A reference to an image of type T that has been snapshotted at a particular moment in time.

See the Snapshot documentation for a full explanation of how Regina's snapshotting machinery works.

As a quick recap:

• There can be many SnapshotRef references all pointing to the same image. The underlying snapshot is guaranteed to exist and maintain the same value for as long as there is some SnapshotRef that refers to it, even if the original type T object has since been modified or destroyed.
• The user of a SnapshotRef R must only access the snapshotted image through the dereference operators *R and R->. This access must remain read-only, and any attempt to circumvent it could lead to a regina::SnapshotWriteError exception being thrown.
• The user of a SnapshotRef should not keep a pointer or reference to the underlying type T object, since the snapshot may switch to a different internal type T object if the original is ever modified or destroyed.

These references are lightweight objects that can be freely copied by value. They do also offer move and swap operations that in some cases are more efficient (though all copy, move and swap operations are fast).

Python

Not present.

Constructor & Destructor Documentation

SnapshotRef() [1/3]

template<class T >

regina::SnapshotRef< T >::SnapshotRef ( const T &  src )

inline

< The snapshot that we are referencing.

This is held by pointer to support assignment; it must not be null. Creates a new snapshot reference to the given object in its current state.

If you already have a snapshot reference R to the same object in the same state, it is (slightly) cheaper to copy R instead of going through the source object src.

Parameters

src	the underlying type T object whose current snapshot we wish to maintain a reference to.

SnapshotRef() [2/3]

template<class T >

regina::SnapshotRef< T >::SnapshotRef ( const SnapshotRef< T > &  src )

inline

Creates a new copy of the given snapshot reference.

The new reference will refer to the same object as src, as it appeared at the same point in time.

Parameters

src	the snapshot reference to copy.

SnapshotRef() [3/3]

template<class T >

regina::SnapshotRef< T >::SnapshotRef ( SnapshotRef< T > &&  src )

inlinenoexcept

Moves the given snapshot reference into this new reference.

The new reference will refer to the same object as src, as it appeared at the same point in time.

This move constructor is identical to the copy constructor, and there is no particular reason to call it. It is included here for consistency because the move assignment operator is different from (and more efficient) than copy assignment.

Parameters

src	the snapshot reference to move.

~SnapshotRef()

template<class T >

regina::SnapshotRef< T >::~SnapshotRef ( )

inline

Destroys this snapshot reference.

If this is the last surviving reference to the underlying snapshot, then the snapshot itself (along with its internal deep copy of the original object, if it made one) will be destroyed.

Member Function Documentation

operator!=()

template<class T >

bool regina::SnapshotRef< T >::operator!= ( const SnapshotRef< T > &  rhs ) const

inline

Tests whether this and the given snapshot reference do not refer to the same snapshot of the same type T object.

This will be true if either the two references were obtained from different type T objects (possibly via copies/moves/swaps from other references), or if they were obtained from the same type T object but at times that were separated by a modification of this type T object.

Parameters

rhs	the snapshot reference to compare with this.

Returns

true if and only if this and rhs do not refer to the same snapshot of the same underlying type T object.

operator*()

template<class T >

const T & regina::SnapshotRef< T >::operator* ( ) const

inline

Gives read-only access to the image that was snapshotted.

Note that this dereference operator may refer to different objects in memory at different times (according to how the snapshots are being managed and copied behind the scenes). Therefore you should always access the snapshot through these dereference operators, and never take your own reference or pointer to the underlying type T object.

Returns

a reference to the snapshot of the type T object.

operator->()

template<class T >

const T * regina::SnapshotRef< T >::operator-> ( ) const

inline

Gives read-only access to the image that was snapshotted.

Note that this dereference operator may refer to different objects in memory at different times (according to how the snapshots are being managed and copied behind the scenes). Therefore you should always access the snapshot through these dereference operators, and never take your own reference or pointer to the underlying type T object.

Returns

a reference to the snapshot of the type T object.

operator=() [1/3]

template<class T >

SnapshotRef & regina::SnapshotRef< T >::operator= ( const SnapshotRef< T > &  src )

inline

Sets this to be a copy of the given snapshot reference.

This reference will be made to refer to the same object as src, as it appeared at the same point in time.

If the old value of this reference was the last surviving reference to its underlying snapshot, then the old snapshot itself (along with its internal deep copy of the original object, if it made one) will be destroyed.

Self-assignment (r = r) is harmless, and will never cause the underlying snapshot to be destroyed.

Parameters

src	the snapshot reference to copy.

Returns

a reference to this object.

operator=() [2/3]

template<class T >

SnapshotRef & regina::SnapshotRef< T >::operator= ( const T &  src )

inline

Sets this to be a snapshot of the given object in its current state.

If you already have a snapshot reference R to the same object in the same state, it is (slightly) cheaper to assign from R instead of assigning from the source object src.

If the old value of this reference was the last surviving reference to its underlying snapshot, then the old snapshot itself (along with its internal deep copy of the original object, if it made one) will be destroyed.

Self-assignment (r = *r) is harmless, and will never cause the underlying snapshot to be destroyed.

Parameters

src	the underlying type T object whose current snapshot we wish to make this a reference to.

Returns

a reference to this object.

operator=() [3/3]

template<class T >

SnapshotRef & regina::SnapshotRef< T >::operator= ( SnapshotRef< T > &&  src )

inlinenoexcept

Moves the given snapshot reference into this new reference.

The new reference will refer to the same object as src, as it appeared at the same point in time.

This is more efficient than copy assignment, since it avoids atomic changes to reference counts.

Parameters

src	the snapshot reference to move.

Returns

a reference to this object.

operator==()

template<class T >

bool regina::SnapshotRef< T >::operator== ( const SnapshotRef< T > &  rhs ) const

inline

Tests whether this and the given snapshot reference refer to the same snapshot of the same type T object.

This will be true if and only if both references were obtained from the same type T object (possibly via copies/moves/swaps from other references), during the same time period in which the underlying type T object was not modified.

Parameters

rhs	the snapshot reference to compare with this.

Returns

true if and only if this and rhs refer to the same snapshot of the same underlying type T object.

swap()

template<class T >

void regina::SnapshotRef< T >::swap ( SnapshotRef< T > &  other )

inlinenoexcept

Swaps this and the given reference so that they refer to each others' snapshots.

Self-swapping (r.swap(r)) is harmless, and will never cause the underlying snapshot to be destroyed.

This is more efficient than a sequence of copies, since it avoids atomic changes to reference counts.

Parameters

other

the reference to swap with this.

---

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

• utilities/snapshot.h