regina::ProgressTrackerBase Class Reference
Progress Tracking

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

`#include <progress/progresstracker.h>`

Inheritance diagram for regina::ProgressTrackerBase:

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

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

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

regina::ProgressTrackerBase::ProgressTrackerBase | ( |  | ) |

inline protected

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

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.

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

## 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_

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.

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

- progress/progresstracker.h

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