The base class for Regina's progress tracking classes. More...
#include <progress/progresstracker.h>
Public Member Functions | |
| 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 | setFinished () |
| Used by the writing thread to indicate that it has finished all processing. More... | |
| ProgressTrackerBase (const ProgressTrackerBase &)=delete | |
| ProgressTrackerBase & | operator= (const ProgressTrackerBase &)=delete |
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.
- The reading thread creates a progress tracker (of type ProgressTracker or ProgressTrackerOpen), and passes it to the writing thread when the calculation begins.
- The writing thread:
- creates the first stage by calling newStage();
- as the stage progresses, repeatedly updates the progress of this stage by calling routines such as ProgressTracker::setPercent() or ProgressTrackerOpen::incSteps(), and also polls for cancellation by calling isCancelled();
- moves through any additional stages in a similar fashion, by calling newStage() and then repeatedly calling routines such as ProgressTracker::setPercent(), ProgressTrackerOpen::incSteps(), and isCancelled();
- calls setFinished() once all processing is complete (regardless of whether the operation finished naturally or was cancelled by the user);
- never touches the progress tracker again.
- The reading thread:
- passes the progress tracker to the writing thread;
- repeatedly polls the state of the tracker by calling routines such as ProgressTracker::percentChanged(), ProgressTrackerOpen::stepsChanged(), descriptionChanged() and/or isFinished();
- if percentChanged() or stepsChanged() returns
true, collects the total progress by calling percent() or steps() respectively and displays this to the user; - if descriptionChanged() returns
true, collects the description of the current stage by calling description() and displays this to the user; - if the user ever chooses to cancel the operation, calls cancel() but continues polling the state of the tracker as above;
- once isFinished() returns
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.
Progress trackers rely on multiple threads accessing the same underlying object, and so they cannot be copied, moved or swapped.
- 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).
Constructor & Destructor Documentation
◆ 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.
Member Function Documentation
◆ 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()
|
inline |
Returns the human-readable description of the current stage.
This is typically called by the reading thread.
- Returns
thecurrent stage description.
◆ 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
trueif and only if the stage description has changed.
◆ 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
trueif and only if a cancellation request has been made.
◆ 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
trueif and only if the writing thread has finished all processing.
◆ setFinished()
| 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().
Member Data Documentation
◆ cancelled_
|
protected |
Has the reading thread requested that the operation be cancelled?
◆ desc_
|
protected |
The human-readable description of the current stage.
◆ descChanged_
|
protected |
Has the description changed since the last call to descriptionChanged()?
◆ finished_
|
protected |
Has the writing thread declared that it has finished all processing?
◆ lock_
|
mutableprotected |
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