regina::NProgress Class Referenceabstract
Progress Management

An object through which external interfaces can obtain progress reports when running long calculations. More...

`#include <progress/nprogress.h>`

Inheritance diagram for regina::NProgress:

## Public Member Functions

| NProgress ()
| Performs basic initialisation. More...
virtual | ~NProgress ()
| Destroys this object. More...
bool | hasChanged () const
| Determines if the state of progress has changed since the last query. More...
bool | isFinished () const
| Is the operation whose progress we are reporting completely finished? More...
void | setFinished ()
| Signifies that the operation whose progress we are reporting is completely finished. More...
void | cancel () const
| Called by an external interface to request that the operation whose progress we are reporting be cancelled. More...
bool | isCancelled () const
| Determines whether an external interface has requested that the operation whose progress we are reporting be cancelled. More...
std::string | getDescription () const
| Returns a string description of the current state of progress. More...
virtual bool | isPercent () const
| Determines if the state of progress can be expressed as a percentage. More...
double | getPercent () const
| Returns the current state of progress as a percentage. More...
long | getRealTime () const
| Returns the real time elapsed since this operation began. More...
long | totalCPUTime () const
| Returns the total CPU time consumed by the program from the beginning to the end of this operation. More...
void | writeTextShort (std::ostream &out) const
| Writes this object in short text format to the given output stream. More...
Public Member Functions inherited from regina::ShareableObject
| ShareableObject ()
| Default constructor that does nothing. More...
virtual | ~ShareableObject ()
| Default destructor that does nothing. More...
virtual void | writeTextLong (std::ostream &out) const
| Writes this object in long text format to the given output stream. More...
std::string | str () const
| Returns the output from writeTextShort() as a string. More...
std::string | toString () const
| A deprecated alias for str(), which returns the output from writeTextShort() as a string. More...
std::string | detail () const
| Returns the output from writeTextLong() as a string. More...
std::string | toStringLong () const
| A deprecated alias for detail(), which returns the output from writeTextLong() as a string. More...

## Protected Member Functions

virtual std::string | internalGetDescription () const =0
| Returns a string description of the current state of progress. More...
virtual double | internalGetPercent () const
| Returns the current state of progress as a percentage. More...
Protected Member Functions inherited from regina::boost::noncopyable
| noncopyable ()
| A constructor which does nothing. More...
| ~noncopyable ()
| A destructor which does nothing. More...
Protected Member Functions inherited from regina::NMutex
| NMutex ()
| Creates a new mutex. More...
| ~NMutex ()
| Destroys this mutex. More...

## Protected Attributes

bool | changed
| Has the state of progress changed since the last query? More...
bool | cancelled
| Has this operation been cancelled? More...

## Detailed Description

An object through which external interfaces can obtain progress reports when running long calculations.

The running calculation writes to this object to store the current state of progress, and the external interface reads from this object from a different thread.

When writing progress information to an NProgress object, the last call should be to setFinished(). This informs all threads that the operation is finished and that the NProgress object can be deleted without the risk that the writing thread will attempt to access it again.

If the operation allows it, the reading thread may at any time request that the operation be cancelled by calling cancel(). The writing thread should regularly poll isCancelled(), and if it detects a cancellation request should exit cleanly as soon as possible. Note that the writing thread should still call setFinished() in this situation.

NProgress contains multithreading support; a mutex is used to ensure that the reading and writing threads do not interfere.

NProgress also contains timing support, with measurements in both real time and CPU time. See the routines getRealTime() and totalCPUTime() for details.

Subclasses of NProgress represent the various ways in which progress can be internally stored. Note that subclass member functions must lock the mutex whenever internal data is being accessed or modified (see NMutex::MutexLock for how this is done). Any public subclass member function that changes the state of progress must set the changed flag to `true`, and all public subclass query functions must set the changed flag to `false`.

Deprecated:
  This class is deprecated. Please use the more flexible and more streamlined NProgressTracker class instead.

## Constructor & Destructor Documentation

regina::NProgress::NProgress | ( |  | ) |

inline

Performs basic initialisation.

Note that the internal mutex is not locked during construction.

The internal state-has-changed flag is set to `true`.

Python:
  Not present; NProgress objects should only be created within calculation engine routines whose progress is being watched.

regina::NProgress::~NProgress | ( |  | ) |

inline virtual

Destroys this object.

## Member Function Documentation

void regina::NProgress::cancel | ( |  | ) | const

inline

Called by an external interface to request that the operation whose progress we are reporting be cancelled.

The operation itself should regularly poll isCancelled() to check if an external interface has made this request.

Note that if cancellation is not sensible or appropriate, the operation may freely ignore such cancellation requests and need not poll isCancelled() at all.

This routine is made const since an external interface should be able to cancel an operation even though it should never modify the state of progress.

std::string regina::NProgress::getDescription | ( |  | ) | const

inline

Returns a string description of the current state of progress.

Note that subclasses must override internalGetDescription(), not this routine.

Returns
  the current state of progress.

double regina::NProgress::getPercent | ( |  | ) | const

inline

Returns the current state of progress as a percentage.

Note that subclasses must override internalGetPercent(), not this routine.

Precondition
  Progress can be expressed as a percentage (see isPercent()).

Returns
  the current state of progress as a percentage.

long regina::NProgress::getRealTime | ( |  | ) | const

inline

Returns the real time elapsed since this operation began.

This routine may be called both during and after the operation.

If the operation has been marked as finished, the total elapsed time from start to finish will be reported. Otherwise the time elasped thus far will be reported.

Returns
  the total elapsed real time, measured in seconds.

See Also
  totalCPUTime()

bool regina::NProgress::hasChanged | ( |  | ) | const

inline

Determines if the state of progress has changed since the last query.

A query is defined to be a call to getDescription(), getPercent() or any of the subclass-specific query routines.

This routine allows interfaces to avoid calls to the slower query routines when they can avoid it.

If no query has yet been made, this routine will return `true`.

Returns
  `true` if and only if the state of progress has changed since the last query.

virtual std::string regina::NProgress::internalGetDescription | ( |  | ) | const

protected pure virtual

Returns a string description of the current state of progress.

This function must not touch the mutex, and is not required to alter the changed flag. The getDescription() routine takes care of all of these issues.

Precondition
  The mutex is currently locked.

Returns
  the current state of progress.

Implemented in regina::NProgressFinished, regina::NProgressNumber, and regina::NProgressMessage.

double regina::NProgress::internalGetPercent | ( |  | ) | const

inline protected virtual

Returns the current state of progress as a percentage.

The default implementation returns 0.

This function must not touch the mutex, and is not required to alter the changed flag. The getDescription() routine takes care of all of these issues.

Precondition
  Progress can be expressed as a percentage (see isPercent()).
  The mutex is currently locked.

Returns
  the current state of progress as a percentage.

Reimplemented in regina::NProgressFinished, and regina::NProgressNumber.

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

inline

Determines whether an external interface has requested that the operation whose progress we are reporting be cancelled.

If the operation is polling for cancellation requests and it finds that isCancelled() returns `true`, it should generally exit (cleanly) as soon as possible with only partial or no results. However, if cancellation is not sensible or appropriate, the operation may freely ignore such cancellation requests.

Note that even if the underlying operation cancels itself, it should still call setFinished().

Returns
  `true` if and only if an external interface has requested that the operation be cancelled.

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

inline

Is the operation whose progress we are reporting completely finished?

Once this routine returns `true`, it will always return `true`; thus there will be no need to call it again.

Returns
  `true` if and only if the operation is finished.

bool regina::NProgress::isPercent | ( |  | ) | const

inline virtual

Determines if the state of progress can be expressed as a percentage.

The default implementation returns `false`.

Returns
  `true` if and only if progress can be expressed as a percentage.

Reimplemented in regina::NProgressFinished, and regina::NProgressNumber.

void regina::NProgress::setFinished | ( |  | ) |

inline

Signifies that the operation whose progress we are reporting is completely finished.

This must be the final member function call to this NProgress object made by the thread performing the corresponding operation. It notifies all other threads that the operation is complete and that this NProgress object can be safely deleted.

This routine should still be called by the operation thread if it cancels itself in response to a request by an external interface (see cancel()).

Python:
  Not present; this should only be called from within the calculation engine routine whose progress is being watched.

long regina::NProgress::totalCPUTime | ( |  | ) | const

inline

Returns the total CPU time consumed by the program from the beginning to the end of this operation.

This routine will only return useful results after the operation has finished.

If the operation has not yet been marked as finished, this routine will return 0.

Warning
  For CPU time calculations to be correct, the same thread that constructs this progress object must also mark it finished.

Returns
  the total CPU time consumed, measured in seconds.

See Also
  getRealTime()

void regina::NProgress::writeTextShort | ( | std::ostream & | out | ) | const

inline virtual

Writes this object in short text format to the given output stream.

The output should be human-readable, should fit on a single line, and should not end with a newline.

Python:
  The parameter out does not exist; standard output will be used.

Parameters

  out | the output stream to which to write.

Implements regina::ShareableObject.

## Member Data Documentation

bool regina::NProgress::cancelled

protected

Has this operation been cancelled?

bool regina::NProgress::changed

mutable protected

Has the state of progress changed since the last query?

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

- progress/nprogress.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).