regina::ProgressTrackerOpen Class Reference
Progress Tracking

Manages percentage-based progress tracking and cancellation polling for open-ended operations. More...

`#include <progress/progresstracker.h>`

Inheritance diagram for regina::ProgressTrackerOpen:

## Public Member Functions

| ProgressTrackerOpen ()
| Creates a new progress tracker. More...
bool | stepsChanged ()
| Queries whether the number of steps completed has changed since the last call to stepsChanged(). More...
unsigned long | steps ()
| Returns the number of steps completed throughout the entire operation. More...
void | newStage (const char *desc)
| Used by the writing thread to indicate that it has moved on to a new stage of processing. More...
void | newStage (const std::string &desc)
| Used by the writing thread to indicate that it has moved on to a new stage of processing. More...
bool | incSteps ()
| Used by the writing thread to indicate that one more step has been completed. More...
bool | incSteps (unsigned long add)
| Used by the writing thread to indicate that some number of additional steps have been completed. More...
void | setFinished ()
| Used by the writing thread to indicate that it has finished all processing. More...
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...

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

Manages percentage-based progress tracking and cancellation polling for open-ended operations.

See the ProgressTrackerBase documentation for detailed information on how to use a progress tracker.

This class represents a progress tracker that measures progress using a non-negative integer, which typically indicates the number of steps completed so far during the operation. This integer begin at 0 and rises as the operation progresses. There is no particular "end point" or upper bound on the number of steps, and indeed the end point is often unknown until the operation has finished.

## Constructor & Destructor Documentation

## ProgressTrackerOpen()

regina::ProgressTrackerOpen::ProgressTrackerOpen | ( |  | ) |

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

This is typically called by the reading thread.

## Member Function Documentation

## cancel()

void regina::ProgressTrackerBase::cancel | ( |  | ) |

inline inherited

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 inherited

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 inherited

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.

## incSteps() [1/2]

bool regina::ProgressTrackerOpen::incSteps | ( |  | ) |

inline

Used by the writing thread to indicate that one more step has been completed.

This is typically called by the writing thread.

Returns
  `true` if there has been no cancellation request, or `false` if cancel() has been called (typically by the reading thread).

## incSteps() [2/2]

bool regina::ProgressTrackerOpen::incSteps | ( | unsigned long | add | ) |

inline

Used by the writing thread to indicate that some number of additional steps have been completed.

This is typically called by the writing thread.

Parameters

  add | the number of additional steps that have been completed. The value returned by steps() will increase by this amount.

Returns
  `true` if there has been no cancellation request, or `false` if cancel() has been called (typically by the reading thread).

## isCancelled()

bool regina::ProgressTrackerBase::isCancelled | ( |  | ) |

inline inherited

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 inherited

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.

## newStage() [1/2]

void regina::ProgressTrackerOpen::newStage | ( | const char * | desc | ) |

inline

Used by the writing thread to indicate that it has moved on to a new stage of processing.

The number of steps completed will be left unchanged.

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

## newStage() [2/2]

void regina::ProgressTrackerOpen::newStage | ( | const std::string & | desc | ) |

inline

Used by the writing thread to indicate that it has moved on to a new stage of processing.

The number of steps completed will be left unchanged.

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

## setFinished()

void regina::ProgressTrackerOpen::setFinished | ( |  | ) |

inline

Used by the writing thread to indicate that it has finished all processing.

The total number of steps completed will be left unchanged, but the stage description will be updated to indicate that the operation is finished.

This is typically called by the writing thread.

## steps()

unsigned long regina::ProgressTrackerOpen::steps | ( |  | ) |

inline

Returns the number of steps completed throughout the entire operation.

This counts the progress across all stages (both current and previous).

This is typically called by the reading thread.

Returns
  the current number of steps completed.

## stepsChanged()

bool regina::ProgressTrackerOpen::stepsChanged | ( |  | ) |

inline

Queries whether the number of steps completed has changed since the last call to stepsChanged().

If this is the first time stepsChanged() is called, the result will be `true`.

This is typically called by the reading thread.

Returns
  `true` if and only if the number of steps completed has changed.

## Member Data Documentation

## cancelled_

bool regina::ProgressTrackerBase::cancelled_

protected inherited

Has the reading thread requested that the operation be cancelled?

## desc_

std::string regina::ProgressTrackerBase::desc_

protected inherited

The human-readable description of the current stage.

## descChanged_

bool regina::ProgressTrackerBase::descChanged_

protected inherited

Has the description changed since the last call to descriptionChanged()?

## finished_

bool regina::ProgressTrackerBase::finished_

protected inherited

Has the writing thread declared that it has finished all processing?

## lock_

std::mutex regina::ProgressTrackerBase::lock_

protected inherited

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