regina::NProgressTracker Class Reference
Progress Management

Manages progress tracking and cancellation polling for long operations. More...

`#include <progress/nprogresstracker.h>`

## Public Member Functions

| NProgressTracker ()
| Creates a new progress tracker. More...
bool | isFinished () const
| Queries whether the writing thread has finished all processing. More...
bool | percentChanged () const
| Queries whether the percentage progress has changed since the last call to percentChanged(). More...
bool | descriptionChanged () const
| Queries whether the stage description has changed since the last call to descriptionChanged(). More...
double | percent () const
| Returns the percentage progress through the entire operation. 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...
void | 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...
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...
bool | setPercent (double percent)
| Used by the writing thread to indicate the level of progress through the current stage. More...
void | setFinished ()
| Used by the writing thread to indicate that it has finished all processing. More...

## Detailed Description

Manages 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 percentage progress that rises from 0 to 100 as the stage progresses. Each stage also has a fractional weight (between 0 and 1 inclusive), and the percentage progress of the entire calculation is taken to be the weighted sum of the progress of the individual stages. The weights of all stages should sum to 1.

The life cycle of an NProgressTracker is as follows.

- The reading thread creates an NProgressTracker, 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 percentage progress of this stage by calling setPercent() and polls for cancellation by calling isCancelled();
  - moves through any additional stages in a similar fashion, by calling newStage() and then repeatedly calling setPercent() 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 percentChanged(), descriptionChanged() and/or isFinished();
  - if percentChanged() returns `true`, collects the total percentage progress by calling percent() 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 NProgressTracker.

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.

## Constructor & Destructor Documentation

regina::NProgressTracker::NProgressTracker | ( |  | ) |

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.

## Member Function Documentation

void regina::NProgressTracker::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.

std::string regina::NProgressTracker::description | ( |  | ) | const

inline

Returns the human-readable description of the current stage.

This is typically called by the reading thread.

Returns
  `the` current stage description.

bool regina::NProgressTracker::descriptionChanged | ( |  | ) | const

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.

bool regina::NProgressTracker::isCancelled | ( |  | ) | const

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.

bool regina::NProgressTracker::isFinished | ( |  | ) | const

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.

void regina::NProgressTracker::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

  desc | a human-readable description of the new stage. Typically this begins with a capital and does not include a final period (full stop).
  weight | the 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.

double regina::NProgressTracker::percent | ( |  | ) | const

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.

bool regina::NProgressTracker::percentChanged | ( |  | ) | const

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.

void regina::NProgressTracker::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.

bool regina::NProgressTracker::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

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

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

- progress/nprogresstracker.h

Copyright © 1999-2013, 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@debian.org).