Regina 7.3 Calculation Engine
Public Member Functions | Protected Attributes | List of all members
regina::ProgressTracker Class Reference

Manages percentage-based progress tracking and cancellation polling for long operations. More...

#include <progress/progresstracker.h>

Inheritance diagram for regina::ProgressTracker:
regina::ProgressTrackerBase regina::ShortOutput< ProgressTracker > regina::Output< ProgressTracker, false >

Public Member Functions

 ProgressTracker ()
 Creates a new progress tracker. More...
 
bool percentChanged () const
 Queries whether the percentage progress has changed since the last call to percentChanged(). More...
 
double percent () const
 Returns the percentage progress through the entire operation. More...
 
void newStage (std::string desc, double weight=1)
 Used by the writing thread to indicate that it has moved on to a new stage of processing. More...
 
bool setPercent (double percent)
 Used by the writing thread to indicate the level of progress through the current stage. More...
 
void setFinished ()
 Used by the writing thread to indicate that it has finished all processing. More...
 
void writeTextShort (std::ostream &out) const
 Writes a short text representation of this object to the given output stream. More...
 
bool isFinished () const
 Queries whether the writing thread has finished all processing. More...
 
bool descriptionChanged () const
 Queries whether the stage description has changed since the last call to descriptionChanged(). More...
 
std::string description () const
 Returns the human-readable description of the current stage. More...
 
void cancel ()
 Indicates to the writing thread that the user wishes to cancel the operation. More...
 
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. More...
 
void writeTextLong (std::ostream &out) const
 A default implementation for detailed output. More...
 
std::string str () const
 Returns a short text representation of this object. More...
 
std::string utf8 () const
 Returns a short text representation of this object using unicode characters. More...
 
std::string detail () const
 Returns a detailed text representation of this object. More...
 

Protected Attributes

std::string desc_
 The human-readable description of the current stage. More...
 
bool descChanged_
 Has the description changed since the last call to descriptionChanged()? More...
 
bool cancelled_
 Has the reading thread requested that the operation be cancelled? More...
 
bool finished_
 Has the writing thread declared that it has finished all processing? More...
 
std::mutex lock_
 A mutex to stop the reading and writing threads from interfering with each other. More...
 

Detailed Description

Manages percentage-based progress tracking and cancellation polling for long 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 percentages. Specifically, each stage has a percentage progress that rises from 0 to 100 as the stage progresses. Each stage also has a fractional weight (between 0 and 1 inclusive), and the percentage progress of the entire calculation is taken to be the weighted sum of the progress of the individual stages. The weights of all stages should sum to 1.

Constructor & Destructor Documentation

◆ ProgressTracker()

regina::ProgressTracker::ProgressTracker ( )
inline

Creates a new progress tracker.

This sets a sensible state description (which declares that the operation is initialising), and marks the current progress as zero percent complete.

This is typically called by the reading thread.

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< ProgressTracker , 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::ProgressTracker::newStage ( std::string  desc,
double  weight = 1 
)
inline

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

The percentage progress through the current stage will automatically be set to 100.

This is typically called by the writing thread.

Parameters
desca human-readable description of the new stage. Typically this begins with a capital and does not include a final period (full stop).
weightthe relative weight of this stage as a fraction of the entire operation. This weight must be between 0 and 1 inclusive, and the weights of all stages must sum to 1 in total.

◆ percent()

double regina::ProgressTracker::percent ( ) const
inline

Returns the percentage progress through the entire operation.

This combines the progress through the current stage with all previous stages, taking into account the relative weights that the writing thread has passed to newStage().

This is typically called by the reading thread.

Returns
the current percentage progress.

◆ percentChanged()

bool regina::ProgressTracker::percentChanged ( ) const
inline

Queries whether the percentage progress has changed since the last call to percentChanged().

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

This is typically called by the reading thread.

Returns
true if and only if the percentage progress has changed.

◆ setFinished()

void regina::ProgressTracker::setFinished ( )
inline

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

The percentage progress through both the current stage and the entire operation will automatically be set to 100, and the stage description will be updated to indicate that the operation is finished.

This is typically called by the writing thread.

◆ setPercent()

bool regina::ProgressTracker::setPercent ( double  percent)
inline

Used by the writing thread to indicate the level of progress through the current stage.

Unlike percent(), which measures progress in the context of the entire operation, this routine takes a percentage that is strictly relative to the current stage (i.e., the stage most recently declared through a call to newStage()). When the stage begins, setPercent() would typically be given a figure close to 0; when the stage is finished, setPercent() would typically be given a figure close to 100.

There is no actual need to call setPercent(0) at the beginning of the stage or setPercent(100) at the end of the stage, since other routines (such as the constructor, newStage() and setFinished()) will take care of this for you.

This is typically called by the writing thread.

Parameters
percentthe percentage progress through this stage, as a number between 0 and 100 inclusive.
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< ProgressTracker , 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< ProgressTracker , 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< ProgressTracker , 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
outthe output stream to which to write.

◆ writeTextShort()

void regina::ProgressTracker::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
outthe 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:

Copyright © 1999-2023, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).