Manages objective-based progress tracking and cancellation polling for open-ended operations. More...

#include <progress/progresstracker.h>

Inheritance diagram for regina::ProgressTrackerObjective:

Public Member Functions
	ProgressTrackerObjective (long objective)
	Creates a new progress tracker.

bool	objectiveChanged () const
	Queries whether the objective value has changed since the last call to objectiveChanged().

long	objective () const
	Returns the current value of the objective.

void	newStage (std::string desc)
	Used by the writing thread to indicate that it has moved on to a new stage of processing.

bool	setObjective (long objective)
	Used by the writing thread to indicate that a new objective value has been obtained.

void	setFinished ()
	Used by the writing thread to indicate that it has finished all processing.

void	writeTextShort (std::ostream &out) const
	Writes a short text representation of this object to the given output stream.

bool	isFinished () const
	Queries whether the writing thread has finished all processing.

bool	descriptionChanged () const
	Queries whether the stage description has changed since the last call to descriptionChanged().

std::string	description () const
	Returns the human-readable description of the current stage.

void	cancel ()
	Indicates to the writing thread that the user wishes to cancel the operation.

bool	isCancelled () const
	Queries whether the reading thread has made a request for the writing thread to cancel the operation; in other words, whether cancel() has been called.

void	writeTextLong (std::ostream &out) const
	A default implementation for detailed output.

std::string	str () const
	Returns a short text representation of this object.

std::string	utf8 () const
	Returns a short text representation of this object using unicode characters.

std::string	detail () const
	Returns a detailed text representation of this object.

Protected Attributes
std::string	desc_
	The human-readable description of the current stage.

bool	descChanged_
	Has the description changed since the last call to descriptionChanged()?

bool	cancelled_
	Has the reading thread requested that the operation be cancelled?

bool	finished_
	Has the writing thread declared that it has finished all processing?

std::mutex	lock_
	A mutex to stop the reading and writing threads from interfering with each other.

Detailed Description

Manages objective-based progress tracking and cancellation polling for open-ended operations.

See the ProgressTrackerBase documentation for detailed information on how to use a progress tracker.

This class represents a progress tracker that measures progress using some integer objective, whose value might rise and/or fall as the operation progresses. (An example might be the number of top-dimensional simplices in a triangulation that the operation is trying to simplify.) The initial value of the objective must be supplied to the constructor, and there is no particular "end point" that we are aiming for.

Constructor & Destructor Documentation

◆ ProgressTrackerObjective()

regina::ProgressTrackerObjective::ProgressTrackerObjective ( long objective )

inline

Creates a new progress tracker.

This sets a sensible state description (which declares that the operation is initialising), and sets the objective to the given value.

This is typically called by the reading thread.

Parameters

objective the initial value for the objective.

Member Function Documentation

◆ cancel()

void regina::ProgressTrackerBase::cancel ( )

inlineinherited

Indicates to the writing thread that the user wishes to cancel the operation.

The writing thread might not detect and/or respond to this request immediately (or indeed ever), and so the reading thread should continue to wait until isFinished() returns true before it cleans up and destroys this progress tracker.

This is typically called by the reading thread.

◆ description()

std::string regina::ProgressTrackerBase::description ( ) const

inlineinherited

Returns the human-readable description of the current stage.

This is typically called by the reading thread.

Returns: the current stage description.

◆ descriptionChanged()

bool regina::ProgressTrackerBase::descriptionChanged ( ) const

inlineinherited

Queries whether the stage description has changed since the last call to descriptionChanged().

If this is the first time descriptionChanged() is called, the result will be true.

This is typically called by the reading thread.

Returns: true if and only if the stage description has changed.

◆ detail()

std::string regina::Output< ProgressTrackerObjective, supportsUtf8 >::detail ( ) const

inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns: a detailed text representation of this object.

◆ isCancelled()

bool regina::ProgressTrackerBase::isCancelled ( ) const

inlineinherited

Queries whether the reading thread has made a request for the writing thread to cancel the operation; in other words, whether cancel() has been called.

This is typically called by the writing thread.

Returns: true if and only if a cancellation request has been made.

◆ isFinished()

bool regina::ProgressTrackerBase::isFinished ( ) const

inlineinherited

Queries whether the writing thread has finished all processing.

This will eventually return true regardless of whether the processing finished naturally or was cancelled by the reading thread.

This is typically called by the reading thread.

Returns: true if and only if the writing thread has finished all processing.

◆ newStage()

void regina::ProgressTrackerObjective::newStage ( std::string desc )

inline

Used by the writing thread to indicate that it has moved on to a new stage of processing.

The objective value will be left unchanged.

This is typically called by the writing thread.

Parameters

desc	a human-readable description of the new stage. Typically this begins with a capital and does not include a final period (full stop).

◆ objective()

long regina::ProgressTrackerObjective::objective ( ) const

inline

Returns the current value of the objective.

This is typically called by the reading thread.

Returns: the current objective value.

◆ objectiveChanged()

bool regina::ProgressTrackerObjective::objectiveChanged ( ) const

inline

Queries whether the objective value has changed since the last call to objectiveChanged().

If this is the first time objectiveChanged() is called, the result will be true.

This is typically called by the reading thread.

Returns: true if and only if the objective value has changed.

◆ setFinished()

void regina::ProgressTrackerObjective::setFinished ( )

inline

Used by the writing thread to indicate that it has finished all processing.

The objective value will be left unchanged, but the stage description will be updated to indicate that the operation is finished.

This is typically called by the writing thread.

◆ setObjective()

bool regina::ProgressTrackerObjective::setObjective ( long objective )

inline

Used by the writing thread to indicate that a new objective value has been obtained.

This is typically called by the writing thread.

Parameters

objective the new value for the objective.

Returns: true if there has been no cancellation request, or false if cancel() has been called (typically by the reading thread).

◆ str()

std::string regina::Output< ProgressTrackerObjective, supportsUtf8 >::str ( ) const

inherited

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python __str__() and __repr__() functions.

Python: The Python "stringification" function __str__() will use precisely this function, and for most classes the Python __repr__() function will incorporate this into its output.

Returns: a short text representation of this object.

◆ utf8()

std::string regina::Output< ProgressTrackerObjective, supportsUtf8 >::utf8 ( ) const

inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned will be encoded in UTF-8.

Returns: a short text representation of this object.

◆ writeTextLong()

void regina::ShortOutput< ProgressTrackerObjective, false >::writeTextLong ( std::ostream & out ) const

inlineinherited

A default implementation for detailed output.

This routine simply calls T::writeTextShort() and appends a final newline.

Python: Not present. Instead you can call detail() from the subclass T, which returns this output as a string.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

void regina::ProgressTrackerObjective::writeTextShort ( std::ostream & out ) const

inline

Writes a short text representation of this object to the given output stream.

Subclasses must not override this routine. They should override writeName() instead.

Python: Not present. Use str() instead.

Parameters

out	the output stream to which to write.

Member Data Documentation

◆ cancelled_

bool regina::ProgressTrackerBase::cancelled_

protectedinherited

Has the reading thread requested that the operation be cancelled?

◆ desc_

std::string regina::ProgressTrackerBase::desc_

protectedinherited

The human-readable description of the current stage.

◆ descChanged_

bool regina::ProgressTrackerBase::descChanged_

protectedinherited

Has the description changed since the last call to descriptionChanged()?

◆ finished_

bool regina::ProgressTrackerBase::finished_

protectedinherited

Has the writing thread declared that it has finished all processing?

◆ lock_

std::mutex regina::ProgressTrackerBase::lock_

mutableprotectedinherited

A mutex to stop the reading and writing threads from interfering with each other.

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

progress/progresstracker.h

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ProgressTrackerObjective()

Member Function Documentation

◆ cancel()

◆ description()

◆ descriptionChanged()

◆ detail()

◆ isCancelled()

◆ isFinished()

◆ newStage()

◆ objective()

◆ objectiveChanged()

◆ setFinished()

◆ setObjective()

◆ str()

◆ utf8()

◆ writeTextLong()

◆ writeTextShort()

Member Data Documentation

◆ cancelled_

◆ desc_

◆ descChanged_

◆ finished_

◆ lock_