Regina Calculation Engine
Classes | Typedefs | Functions | Variables
Progress Tracking

Progress tracking for long operations. More...

Classes

class  regina::ProgressTrackerBase
 The base class for Regina's progress tracking classes. More...
 
class  regina::ProgressTracker
 Manages percentage-based progress tracking and cancellation polling for long operations. More...
 
class  regina::ProgressTrackerOpen
 Manages percentage-based progress tracking and cancellation polling for open-ended operations. More...
 

Typedefs

typedef ProgressTrackerBase regina::NProgressTrackerBase
 Deprecated typedef for backward compatibility. More...
 
typedef ProgressTracker regina::NProgressTracker
 Deprecated typedef for backward compatibility. More...
 
typedef ProgressTrackerOpen regina::NProgressTrackerOpen
 Deprecated typedef for backward compatibility. More...
 

Functions

bool regina::ProgressTrackerBase::isFinished ()
 Queries whether the writing thread has finished all processing. More...
 
bool regina::ProgressTrackerBase::descriptionChanged ()
 Queries whether the stage description has changed since the last call to descriptionChanged(). More...
 
std::string regina::ProgressTrackerBase::description ()
 Returns the human-readable description of the current stage. More...
 
void regina::ProgressTrackerBase::cancel ()
 Indicates to the writing thread that the user wishes to cancel the operation. More...
 
bool regina::ProgressTrackerBase::isCancelled ()
 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 regina::ProgressTrackerBase::setFinished ()
 Used by the writing thread to indicate that it has finished all processing. More...
 
 regina::ProgressTrackerBase::ProgressTrackerBase (const ProgressTrackerBase &)=delete
 
ProgressTrackerBaseregina::ProgressTrackerBase::operator= (const ProgressTrackerBase &)=delete
 
 regina::ProgressTrackerBase::ProgressTrackerBase ()
 Creates a new progress tracker. More...
 
 regina::ProgressTracker::ProgressTracker ()
 Creates a new progress tracker. More...
 
bool regina::ProgressTracker::percentChanged ()
 Queries whether the percentage progress has changed since the last call to percentChanged(). More...
 
double regina::ProgressTracker::percent ()
 Returns the percentage progress through the entire operation. More...
 
void regina::ProgressTracker::newStage (const char *desc, double weight=1)
 Used by the writing thread to indicate that it has moved on to a new stage of processing. More...
 
void regina::ProgressTracker::newStage (const 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 regina::ProgressTracker::setPercent (double percent)
 Used by the writing thread to indicate the level of progress through the current stage. More...
 
void regina::ProgressTracker::setFinished ()
 Used by the writing thread to indicate that it has finished all processing. More...
 
 regina::ProgressTrackerOpen::ProgressTrackerOpen ()
 Creates a new progress tracker. More...
 
bool regina::ProgressTrackerOpen::stepsChanged ()
 Queries whether the number of steps completed has changed since the last call to stepsChanged(). More...
 
unsigned long regina::ProgressTrackerOpen::steps ()
 Returns the number of steps completed throughout the entire operation. More...
 
void regina::ProgressTrackerOpen::newStage (const char *desc)
 Used by the writing thread to indicate that it has moved on to a new stage of processing. More...
 
void regina::ProgressTrackerOpen::newStage (const std::string &desc)
 Used by the writing thread to indicate that it has moved on to a new stage of processing. More...
 
bool regina::ProgressTrackerOpen::incSteps ()
 Used by the writing thread to indicate that one more step has been completed. More...
 
bool regina::ProgressTrackerOpen::incSteps (unsigned long add)
 Used by the writing thread to indicate that some number of additional steps have been completed. More...
 
void regina::ProgressTrackerOpen::setFinished ()
 Used by the writing thread to indicate that it has finished all processing. More...
 

Variables

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

Detailed Description

Progress tracking for long operations.

Typedef Documentation

◆ NProgressTracker

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NProgressTracker has now been renamed to ProgressTracker.

◆ NProgressTrackerBase

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NProgressTrackerBase has now been renamed to ProgressTrackerBase.

◆ NProgressTrackerOpen

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NProgressTrackerOpen has now been renamed to ProgressTrackerOpen.

Function Documentation

◆ cancel()

void regina::ProgressTrackerBase::cancel ( )
inline

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 ( )
inline

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 ( )
inline

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.

◆ incSteps() [1/2]

bool regina::ProgressTrackerOpen::incSteps ( )
inline

Used by the writing thread to indicate that one more step has been completed.

This is typically called by the writing thread.

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

◆ incSteps() [2/2]

bool regina::ProgressTrackerOpen::incSteps ( unsigned long  add)
inline

Used by the writing thread to indicate that some number of additional steps have been completed.

This is typically called by the writing thread.

Parameters
addthe number of additional steps that have been completed. The value returned by steps() will increase by this amount.
Returns
true if there has been no cancellation request, or false if cancel() has been called (typically by the reading thread).

◆ isCancelled()

bool regina::ProgressTrackerBase::isCancelled ( )
inline

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 ( )
inline

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() [1/4]

void regina::ProgressTrackerOpen::newStage ( const char *  desc)
inline

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

The number of steps completed will be left unchanged.

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).

◆ newStage() [2/4]

void regina::ProgressTracker::newStage ( const char *  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.

◆ newStage() [3/4]

void regina::ProgressTrackerOpen::newStage ( const std::string &  desc)
inline

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

The number of steps completed will be left unchanged.

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).

◆ newStage() [4/4]

void regina::ProgressTracker::newStage ( const 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 ( )
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 ( )
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.

◆ 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.

◆ ProgressTrackerBase()

regina::ProgressTrackerBase::ProgressTrackerBase ( )
inlineprotected

Creates a new progress tracker.

This sets a sensible state description (which declares that the operation is initialising).

This is only ever called by subclass constructors.

◆ ProgressTrackerOpen()

regina::ProgressTrackerOpen::ProgressTrackerOpen ( )
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 steps completed.

This is typically called by the reading thread.

◆ setFinished() [1/3]

void regina::ProgressTrackerBase::setFinished ( )

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

The stage description will be updated to indicate that the operation is finished.

This is typically called by the writing thread.

Warning
The base class implementation of this routine should never be called (and indeed, it is declared here but not implemented). You should always call either ProgressTracker::setFinished() or ProgressTrackerOpen::setFinished().

◆ setFinished() [2/3]

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.

◆ setFinished() [3/3]

void regina::ProgressTrackerOpen::setFinished ( )
inline

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

The total number of steps completed 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.

◆ 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).

◆ steps()

unsigned long regina::ProgressTrackerOpen::steps ( )
inline

Returns the number of steps completed throughout the entire operation.

This counts the progress across all stages (both current and previous).

This is typically called by the reading thread.

Returns
the current number of steps completed.

◆ stepsChanged()

bool regina::ProgressTrackerOpen::stepsChanged ( )
inline

Queries whether the number of steps completed has changed since the last call to stepsChanged().

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

This is typically called by the reading thread.

Returns
true if and only if the number of steps completed has changed.

Variable Documentation

◆ cancelled_

bool regina::ProgressTrackerBase::cancelled_
protected

Has the reading thread requested that the operation be cancelled?

◆ desc_

std::string regina::ProgressTrackerBase::desc_
protected

The human-readable description of the current stage.

◆ descChanged_

bool regina::ProgressTrackerBase::descChanged_
protected

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

◆ finished_

bool regina::ProgressTrackerBase::finished_
protected

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

◆ lock_

std::mutex regina::ProgressTrackerBase::lock_
protected

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


Copyright © 1999-2020, 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).