regina::NProgressManager Class Reference
Progress Management

Manages the sharing of an NProgress object between reading and writing threads. More...

`#include <progress/nprogressmanager.h>`

Inheritance diagram for regina::NProgressManager:

## Public Member Functions

| NProgressManager ()
| Creates a new progress manager with no NProgress to manage. More...
| ~NProgressManager ()
| Destroys this manager as well as the corresponding NProgress. More...
bool | isStarted () const
| Determines if an NProgress has been assigned to this manager yet. More...
bool | isFinished () const
| Determines if the NProgress that we are managing has finished. More...
const NProgress * | getProgress () const
| Returns the NProgress that this manager is managing. More...
void | setProgress (NProgress *newProgress)
| Assigns the given NProgress to this manager to manage. More...
void | writeTextShort (std::ostream &out) const
| Writes this object in short text format to the given output stream. More...
Input and Output
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...

## Detailed Description

Manages the sharing of an NProgress object between reading and writing threads.

The life cycle of an NProgressManager and the corresponding NProgress is as follows. Note that the reading thread is the interface thread that is querying the state of progress, and the writing thread is the thread in which the operation is actually being performed.

- Before the operation begins, an NProgressManager is created and both the reading and writing threads have access to it. This can be achieved for instance by having the reading thread create an NProgressManager and pass it to the writing thread as a parameter of the actual operation function call.
- The writing thread:
  - creates a new NProgress and stores it in the NProgressManager using setProgress();
  - updates the NProgress throughout the operation;
  - finally calls NProgress::setFinished() when the operation is complete;
  - does not touch either the NProgress or the NProgressManager again.
- The reading thread:
  - repeatedly calls isStarted() and waits until this returns `true`;
  - now knows the NProgress has been created and begins querying it using getProgress() and displaying progress reports;
  - whilst querying, repeatedly calls isFinished() to test if the operation is complete;
  - once isFinished() returns `true`, displays the final progress message to the user and destroys the NProgressManager.
- Note that the NProgressManager destructor will automatically destroy the NProgress. It is imperative that the writing thread does not touch either the NProgress or the NProgressManager after calling NProgress::setFinished(), since once isFinished() returns `true` the reading thread might destroy the NProgressManager and thus the NProgress at any time. The writing thread cannot destroy these objects because it has no guarantee that the reading thread is not still reading progress reports from them.

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

## Constructor & Destructor Documentation

regina::NProgressManager::NProgressManager | ( |  | ) |

inline

Creates a new progress manager with no NProgress to manage.

regina::NProgressManager::~NProgressManager | ( |  | ) |

inline

Destroys this manager as well as the corresponding NProgress.

Precondition
  There is an NProgress assigned to this manager; that is, isStarted() returns `true`.
  The NProgress that we are managing has finished, that is, isFinished() returns `true`.

## Member Function Documentation

std::string regina::ShareableObject::detail | ( |  | ) | const

inherited

Returns the output from writeTextLong() as a string.

Returns
  a long text representation of this object.

const NProgress * regina::NProgressManager::getProgress | ( |  | ) | const

inline

Returns the NProgress that this manager is managing.

If isStarted() returns `true`, you are guaranteed that this routine will not return zero.

Returns
  the NProgress that this manager is managing, or 0 if an NProgress has not yet been assigned to this manager.

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

inline

Determines if the NProgress that we are managing has finished.

That is, this routine determines if NProgress::isFinished() returns `true`.

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

Precondition
  There is an NProgress assigned to this manager; that is, isStarted() returns `true`.

Returns
  `true` if and only if the NProgress that we are managing has finished.

bool regina::NProgressManager::isStarted | ( |  | ) | const

inline

Determines if an NProgress has been assigned to this manager yet.

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 an NProgress has been assigned to this manager.

void regina::NProgressManager::setProgress | ( | NProgress * | newProgress | ) |

inline

Assigns the given NProgress to this manager to manage.

Precondition
  setProgress() has not already been called.

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

Parameters

  newProgress | the NProgress that this manager will manage.

std::string regina::ShareableObject::str | ( |  | ) | const

inherited

Returns the output from writeTextShort() as a string.

Python:
  This implements the `__str__()` function.

Returns
  a short text representation of this object.

std::string regina::ShareableObject::toString | ( |  | ) | const

inline inherited

A deprecated alias for str(), which returns the output from writeTextShort() as a string.

Deprecated:
  This routine has (at long last) been deprecated; use the simpler-to-type str() instead.

Returns
  a short text representation of this object.

std::string regina::ShareableObject::toStringLong | ( |  | ) | const

inline inherited

A deprecated alias for detail(), which returns the output from writeTextLong() as a string.

Deprecated:
  This routine has (at long last) been deprecated; use the simpler-to-type detail() instead.

Returns
  a long text representation of this object.

void regina::ShareableObject::writeTextLong | ( | std::ostream & | out | ) | const

inline virtual inherited

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

The output should provide the user with all the information they could want. The output should be human-readable, should not contain extremely long lines (so users can read the output in a terminal), and should end with a final newline.

The default implementation of this routine merely calls writeTextShort() and adds a newline.

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

Parameters

  out | the output stream to which to write.

Reimplemented in regina::NSnapPeaTriangulation, regina::NGroupPresentation, regina::NHomMarkedAbelianGroup, regina::NNormalSurfaceList, regina::NTetrahedron, regina::NSatRegion, regina::NVertex, regina::NEdge, regina::Dim2Triangle, regina::NTriangle, regina::NLayeredSolidTorus, regina::NHomGroupPresentation, regina::NGenericIsomorphism< dim >, regina::NGenericIsomorphism< 2 >, regina::NGenericIsomorphism< 3 >, regina::NTriangulation, regina::NComponent, regina::NTxICore, regina::NTriSolidTorus, regina::NAngleStructureList, regina::Dim2Edge, regina::NBoundaryComponent, regina::NLayeredChain, regina::Dim2Vertex, regina::Dim2Component, regina::NScript, regina::NAugTriSolidTorus, regina::NSpiralSolidTorus, regina::NSurfaceFilterProperties, regina::NLayeredTorusBundle, regina::NManifold, regina::NPlugTriSolidTorus, regina::NMatrixInt, regina::NBlockedSFSTriple, regina::NPluggedTorusBundle, regina::Dim2Triangulation, regina::NSurfaceSubset, regina::NLayeredLensSpace, regina::NLayeredLoop, regina::NFileInfo, regina::NBlockedSFSLoop, regina::NSnappedBall, regina::NBlockedSFSPair, regina::Dim2BoundaryComponent, regina::NTrivialTri, regina::NL31Pillow, regina::NLayeredChainPair, regina::NText, regina::NSurfaceFilterCombination, and regina::NBlockedSFS.

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

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

- progress/nprogressmanager.h

Copyright © 1999-2014, 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).