regina::Snapshottable< T > Class Template Reference

A base class for images of type T that can be snapshotted at a particular moment in time. More...

#include <utilities/snapshot.h>

Protected Member Functions
	Snapshottable ()
	Default constructor. More...
	Snapshottable (const Snapshottable &)
	Copy constructor. More...
	Snapshottable (Snapshottable &&src) noexcept
	Move constructor. More...
Snapshottable &	operator= (const Snapshottable &)
	Copy assignment. More...
Snapshottable &	operator= (Snapshottable &&src)
	Move assignment. More...
void	swap (Snapshottable &other) noexcept
	Swap operation. More...
void	takeSnapshot ()
	Must be called before modification and/or destruction of the type T contents. More...
bool	isReadOnlySnapshot () const
	Determines if this object is a read-only deep copy that was created by a snapshot. More...

Friends
class	Snapshot< T >
class	SnapshotRef< T >

Detailed Description

template<class T>
class regina::Snapshottable< T >

A base class for images of type T that can be 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, the requirements for the class T are:

• T must derive from Snapshottable<T>, and must have a copy constructor.
• If T supports any move, copy and/or swap operations, then these must call the corresponding operations from Snapshottable<T>.
• Every modifying member function must call Snapshottable<T>::takeSnapshot() before the modification takes place. There are a handful of exceptions to this requirement, as described below.
• The destructor must likewise call Snapshottable<T>::takeSnapshot() before any data is destroyed.

There are some situations where an object of type T is modified but does not need to call takeSnapshot(). These include:

• move, copy and swap operations, since these are required to call the base class implementations from Snapshottable<T>, which take care of any snapshotting that is required;
• modifications of objects that are freshly constructed, and cannot possibly have snapshots that refer to them yet.

Python

Not present.

Constructor & Destructor Documentation

Snapshottable() [1/3]

template<class T >

regina::Snapshottable< T >::Snapshottable ( )

inlineprotected

Default constructor.

The new object will be unenrolled from the snapshotting machinery.

Snapshottable() [2/3]

template<class T >

regina::Snapshottable< T >::Snapshottable ( const Snapshottable< T > &  )

inlineprotected

Copy constructor.

The new object will be unenrolled from the snapshotting machinery, even if the source object does have a current snapshot.

Snapshottable() [3/3]

template<class T >

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

inlineprotectednoexcept

Move constructor.

This should only be called when the entire type T contents of src are being moved into this new type T object. If src has a current snapshot, then this object will move in as the new image for that same snapshot. This avoids a deep copy of src, even though src is changing (and presumably will be destroyed).

In particular, if the move constructor for T calls this base class constructor (as it should), then there is no need for it to call takeSnapshot() from src.

Parameters

src	the snapshot image being moved.

Member Function Documentation

isReadOnlySnapshot()

template<class T >

bool regina::Snapshottable< T >::isReadOnlySnapshot ( ) const

inlineprotected

Determines if this object is a read-only deep copy that was created by a snapshot.

Recall that, if an image I of type T has a snapshot pointing to it, and if that image I is about to be modified or destroyed, then the snapshot will make an internal deep copy of I and refer to that instead.

The purpose of this routine is to identify whether the current object is such a deep copy. This may be important information, since a snapshot's deep copy is read-only: it must not be modified or destroyed by the outside world. (Of course the only way to access this deep copy is via const reference from the SnapshotRef dereference operators, but there are settings in which this constness is "forgotten", such as Regina's Python bindings.)

Python

Although this Snapshottable base class is not visible to Python, the isReadOnlySnapshot() function is still visible as a member function of the class T.

Returns

true if and only if this object is a deep copy that was taken by a Snapshot object of some original type T image.

operator=() [1/2]

template<class T >

Snapshottable & regina::Snapshottable< T >::operator= ( const Snapshottable< T > &  )

inlineprotected

Copy assignment.

The previous value will have its snapshot taken if necessary, since it will be overwritten. Therefore, if the copy assignment operator for T calls this base class operator (as it should), then it does not need to call takeSnapshot() itself.

The new value will left unenrolled from the snapshotting machinery.

This is safe to use with self-assignment, but this will still behave as though the object were being modified (i.e., it may still take a snapshot).

Returns

a reference to this object.

operator=() [2/2]

template<class T >

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

inlineprotected

Move assignment.

The previous value will have its snapshot taken if necessary, since it will be overwritten. Therefore, if the move assignment operator for T calls this base class operator (as it should), then it does not need to call takeSnapshot() itself.

This should only be called when the entire type T contents of src are being moved into this type T object. If src has a current snapshot, then this object will move in as the new image for that same snapshot. This avoids a deep copy of src, even though src is changing (and presumably will be destroyed).

In particular, if the move assignment operator for T calls this base class operator (again, as it should), then there is no need for it to call takeSnapshot() from src.

This operator is not marked noexcept, since it might create a deep copy of the old type T value of this object.

Parameters

src	the snapshot image being moved.

Returns

a reference to this object.

swap()

template<class T >

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

inlineprotectednoexcept

Swap operation.

This should only be called when the entire type T contents of this object and other are being swapped. If one object has a current snapshot, then the other object will move in as the new image for that same snapshot. This avoids a deep copies of this object and/or other, even though both objects are changing.

In particular, if the swap function for T calls this base class function (as it should), then there is no need to call takeSnapshot() from either this object or src.

Parameters

other

the snapshot image being swapped with this.

takeSnapshot()

template<class T >

void regina::Snapshottable< T >::takeSnapshot ( )

inlineprotected

Must be called before modification and/or destruction of the type T contents.

See the Snapshot class notes for a full explanation of how this requirement works.

There are a few exceptions where takeSnapshot() does not need to be called: these are where type T move, copy and/or swap operations call the base class operations (as they should). See the Snapshottable move, copy and swap functions for details.

If this object has a current snapshot, then this function will trigger a deep copy with the snapshot.

After this function returns, this object is guaranteed to be completely unenrolled from the snapshotting machinery.

---

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

• utilities/snapshot.h