Regina Calculation Engine
|
The base class for Regina's progress tracking classes. More...
#include <progress/progresstracker.h>
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... | |
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.
true
, collects the total progress by calling percent() or steps() respectively and displays this to the user;true
, collects the description of the current stage by calling description() and displays this to the user;true
, displays any final information to the user and destroys the progress tracker.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.