regina::TopologyLockable Class Reference

A base class for objects that support topology locks, such as triangulations or links. More...

#include <utilities/topologylock.h>

Inheritance diagram for regina::TopologyLockable:

Classes
class	TopologyLock
	Creates a temporary lock on the topological properties of the given object. More...

Public Member Functions
	TopologyLockable ()=default
	Default constructor that initialises the lock count to zero.
	TopologyLockable (const TopologyLockable &)=delete
TopologyLockable &	operator= (const TopologyLockable &)=delete

Protected Member Functions
bool	topologyLocked () const
	Returns whether or not there are any topology locks currently held on this object.

Protected Attributes
uint8_t	topologyLock_ { 0 }
	The number of topology locks currently held on this object.

Detailed Description

A base class for objects that support topology locks, such as triangulations or links.

Essentially, a "topology lock" means the following. In routines that would normally clear computed properties of an object (e.g., operations that edit a triangulation or a link diagram), if there are any topology locks currently held on that object then properties that are purely topological will be preserved. This is essentially an optimisation that allows us to avoid recomputing expensive invariants when we know in advance they will not change.

By a "purely topological" property, we mean the following:

• For triangulations, these are properties of the underlying manifold, and must be invariant under reflection. Examples include homology, fundamental group, and Turaev-Viro invariants of 3-manifolds. Non-examples include zero-efficiency of 3-manifold triangulations (which depends upon the specific triangulation), intersection forms of 4-manifolds (which can change under reflection), or validity of triangulations (since subdivision could change a triangulation from invalid to valid).
• For links, these are properties of the underlying link, and they do not need to be invariant under reflection or reversal. Examples include the Jones and HOMFLY-PT polynomials (even though these can change under reflection). Non-examples include the bracket polynomial (which depends upon the specific diagram).

This specific notion of "preserved properties" is subject to change in future versions of Regina.

Currently end users cannot access TopologyLockable or TopologyLock at all; instead topology locks are restricted to member functions, since it is too easy to accidentally abuse them and generate incorrect mathematical results as a result. This may change in a future release of Regina if a good way is found to make them safer for end users.

TopologyLockable should be used as a protected base class for objects that support topology locks (e.g., both Triangulation<dim> and Link derive from TopologyLockable). To create a temporary topology lock on an object obj (e.g., a triangulation or link), typically within a member function (e.g., functions that implement Pachner or Reidemeister moves), you should create a TopologyLock on the stack and pass obj to its constructor.

Subclass implementations should remember:

• TopologyLockable should be a protected base class, since this machinery should not be directly accessible to end users.
• This base class is not copyable, movable or swappable, since topology locks cannot be transferred from one object (e.g., triangulation or link) to another. This means that subclass assignment or swap operations should not touch topology lock counts, and subclass copy/move constructors should always use the default TopologyLockable constructor that sets the lock count to zero.
• In subclass "hook routines" that would normally clear computed properties when an object is modified (such as Link::clearAllProperties(), Triangulation<dim>::clearAllProperties() or TriangulationBase<dim>::clearBaseProperties()), these hook routines should query topologyLocked(), and if this returns true then they should preserve any properties that are purely topological.

/nopython

Constructor & Destructor Documentation

TopologyLockable()

regina::TopologyLockable::TopologyLockable ( )

default

Default constructor that initialises the lock count to zero.

Member Function Documentation

topologyLocked()

bool regina::TopologyLockable::topologyLocked ( ) const

inlineprotected

Returns whether or not there are any topology locks currently held on this object.

Strictly speaking, this routine could return a false negative: the number of locks is stored as an 8-bit integer and so in reality this tests whether the number of locks is a multiple of 256. False negatives are mathematically harmless, since the worst that will happen is that topological properties will be cleared when they could have been preserved, and so unnecessary extra computation may be required to compute them again.

This routine will never return a false positive.

Returns

false if there are no topology locks currently held on this object, or if a false negative occurs (as described above); or true to indicate that there are currently topology locks held on this object.

Member Data Documentation

topologyLock_

uint8_t regina::TopologyLockable::topologyLock_ { 0 }

protected

The number of topology locks currently held on this object.

Any non-zero number of locks implies that "hook routines" that clear computed properties (as described in the class notes) will preserve properties that are purely topological.

---

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

• utilities/topologylock.h