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

The base class for Regina's progress tracking classes. More...

#include <progress/progresstracker.h>

Inheritance diagram for regina::ProgressTrackerBase:
regina::ProgressTracker regina::ProgressTrackerOpen

Public Member Functions

bool isFinished ()
 Queries whether the writing thread has finished all processing. More...
 
bool descriptionChanged ()
 Queries whether the stage description has changed since the last call to descriptionChanged(). More...
 
std::string description ()
 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 ()
 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 setFinished ()
 Used by the writing thread to indicate that it has finished all processing. More...
 

Protected Member Functions

 ProgressTrackerBase ()
 Creates a new progress tracker. 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

The base class for Regina's progress tracking classes.

These classes manage progress tracking and cancellation polling for long operations. A typical progress tracker is simultaneously used by a writing thread, which is performing the long calculations, and a reading thread, which displays progress updates to the user and/or takes cancellation requests from the user.

Progress works through a series of stages. Each stage has a text description, as well as a numerical progress indicator. For the class ProgressTracker, this is a percentage that rises from 0 to 100 as the stage progresses; for ProgressTrackerOpen, this is an integer that starts at 0 and rises (with no particular upper bound).

The life cycle of a progress tracker is as follows.

It is imperative that the writing thread does not access the tracker after calling setFinished(), and it is imperative that the reading thread does not destroy the tracker until after isFinished() returns true. In particular, even if the reading thread has called cancel(), it must still wait upon isFinished() before destroying the tracker. Until isFinished() returns true, there is no guarantee that the writing thread has detected and honoured the cancellation request.

Note
This class implements common functionality for ProgressTracker and ProgressTrackerOpen, and should not be used on its own. Instead, you should always use either ProgressTracker or ProgressTrackerOpen (according to whether you need percentage-based or open-ended progress tracking respectively).

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

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