regina::detail::TriangulationBase< dim >::ChangeAndClearSpan< changeType > Class Template Reference

An object that facilitates taking snapshots, firing change events, and calling clearAllProperties(). More...

#include <triangulation/detail/triangulation.h>

Inheritance diagram for regina::detail::TriangulationBase< dim >::ChangeAndClearSpan< changeType >:

Public Member Functions
	ChangeAndClearSpan (TriangulationBase &tri)
	Performs all initial tasks before the triangulation is modified.
	~ChangeAndClearSpan ()
	Performs all follow-up tasks after the triangulation has been modified.
	ChangeAndClearSpan (const ChangeAndClearSpan &)=delete
ChangeAndClearSpan &	operator= (const ChangeAndClearSpan &)=delete

Detailed Description

template<int dim>
template<ChangeType changeType = ChangeType::General>
class regina::detail::TriangulationBase< dim >::ChangeAndClearSpan< changeType >

An object that facilitates taking snapshots, firing change events, and calling clearAllProperties().

An object of type Triangulation::ChangeAndClearSpan has four possible effects upon the triangulation that is passed to its constructor:

• If the triangulation is actually part of a PacketOf<Triangulation<dim>>, then the packet events PacketListener::packetToBeChanged() and PacketListener::packetWasChanged() will be fired upon this object's construction and destruction respectively.
• On construction, this object also calls Triangulation<dim>::takeSnapshot(). This snapshotting will happen after the initial change event is fired; however, the order of these two operations should be irrelevant since packet listeners should not make any changes to a packet from within PacketListener::packetToBeChanged().
• On destruction, this object also calls Triangulation<dim>::clearAllProperties(), unless the template argument changeType is ChangeType::Cosmetic. This call will happen just before the final change event is fired.
• Finally, if the template argument changeType is ChangeType::PreserveTopology, then this object will effectively create a new TopologyLock for the triangulation that lasts for the full lifespan of this object, excluding the firing of packet change events. Specifically, the TopologyLock will be created in the constructor immediately after snapshotting, and will be removed in the destructor immediately after the call to Triangulation<dim>::clearAllProperties(). In particular, this means that topological properties of the triangulation that have been computed and cached (such as homology and fundamental group) will be preserved when clearAllProperties() is called in the destructor.

The use of ChangeAndClearSpan is similar to Packet::PacketChangeSpan (and indeed, this class is intended to replace PacketChangeSpan when writing Triangulation member functions): objects of this type would typically be created on the stack, just before the internal data within a triangulation is changed, and have a lifespan that covers all of your changes to the triangulation.

Like PacketChangeSpan, these objects can be safely nested with other ChangeAndClearSpan and/or PacketChangeSpan objects, and only the outermost object will fire packet change events. However, unlike PacketChangeSpan, this comes with a cost: as always, only one set of change events will be fired; however, if there are multiple ChangeAndClearSpan objects then Triangulation<dim>::takeSnapshot() and Triangulation<dim>::clearAllProperties() will be called multiple times. This is harmless but inefficient.

Likewise, if changeType is ChangeType::PreserveTopology then these objects will behave in the expected way when nested with other TopologyLock objects (i.e., topological properties will be preserved as long as any such object is alive).

Note: we would normally use a deduction guide so that, for the default case, you can just write ChangeAndClearSpan instead of ChangeAndClearSpan<>. Unfortunately this is not possible due to a gcc bug (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=79501), which affects gcc versions 11 and earlier (but not clang).

ChangeAndClearSpan objects are not copyable, movable or swappable. In particular, Regina does not offer any way for a ChangeAndClearSpan to transfer its outstanding duties (i.e., firing events and calling clearAllProperties() upon destruction) to another object.

Template Parameters

changeType

controls which computed properties of the triangulation will be cleared upon the destruction of this object. See the notes above for details. If unsure, the default value of ChangeType::General (which clears all computed properties) is always safe to use.

Python

Not present.

Constructor & Destructor Documentation

ChangeAndClearSpan()

template<int dim>

template<ChangeType changeType = ChangeType::General>

regina::detail::TriangulationBase< dim >::ChangeAndClearSpan< changeType >::ChangeAndClearSpan ( TriangulationBase &  tri )

inline

Performs all initial tasks before the triangulation is modified.

See the class notes for precisely what tasks are performed.

Parameters

tri	the triangulation whose data is about to change.

~ChangeAndClearSpan()

template<int dim>

template<ChangeType changeType = ChangeType::General>

regina::detail::TriangulationBase< dim >::ChangeAndClearSpan< changeType >::~ChangeAndClearSpan ( )

inline

Performs all follow-up tasks after the triangulation has been modified.

See the class notes for precisely what tasks are performed.

---

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

• triangulation/detail/triangulation.h