A progress report in which the current state of progress is stored as a number of items completed.
More...
#include <progress/nprogresstypes.h>
A progress report in which the current state of progress is stored as a number of items completed.
The expected total number of items can be optionally specified.
- Python:
- Not present; all progress classes communicate with external interfaces through the NProgress interface.
- Deprecated:
- This class is deprecated. Please use the more flexible and more streamlined NProgressTracker class instead.
regina::NProgressNumber::NProgressNumber |
( |
long |
newCompleted = 0 , |
|
|
long |
newOutOf = -1 |
|
) |
| |
|
inline |
Creates a new progress report containing the given details.
Note that the internal mutex is not locked during construction.
- Precondition
- The new number of items completed is non-negative.
-
If the new expected total is non-negative, then the new number of items completed is at most the new expected total.
- Parameters
-
newCompleted | the number of items completed; this defaults to 0. |
newOutOf | the expected total number of items, or -1 if this total is not known (the default). |
void regina::NProgress::cancel |
( |
| ) |
const |
|
inlineinherited |
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::ShareableObject::detail |
( |
| ) |
const |
|
inherited |
long regina::NProgressNumber::getCompleted |
( |
| ) |
const |
|
inline |
Returns the number of items completed.
- Returns
- the number of items completed.
std::string regina::NProgress::getDescription |
( |
| ) |
const |
|
inlineinherited |
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.
Returns both the number of items completed and the expected total number of items.
- Returns
- the current state of progress.
long regina::NProgressNumber::getOutOf |
( |
| ) |
const |
|
inline |
Returns the expected total number of items.
- Returns
- the expected total number of items, or -1 if this total is not known.
double regina::NProgress::getPercent |
( |
| ) |
const |
|
inlineinherited |
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 |
|
inlineinherited |
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 |
|
inlineinherited |
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.
void regina::NProgressNumber::incCompleted |
( |
unsigned long |
extraCompleted = 1 | ) |
|
|
inline |
Increases the number of items completed by the given amount.
- Precondition
- If the expected total is non-negative, then the new total number of items completed is at most the expected total.
- Parameters
-
extraCompleted | the number of items to add to the number of items already completed. |
virtual std::string regina::NProgressNumber::internalGetDescription |
( |
| ) |
const |
|
protectedvirtual |
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.
Implements regina::NProgress.
double regina::NProgressNumber::internalGetPercent |
( |
| ) |
const |
|
inlineprotectedvirtual |
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 from regina::NProgress.
bool regina::NProgress::isCancelled |
( |
| ) |
const |
|
inlineinherited |
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 |
|
inlineinherited |
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::NProgressNumber::isPercent |
( |
| ) |
const |
|
inlinevirtual |
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 from regina::NProgress.
void regina::NProgressNumber::setCompleted |
( |
long |
newCompleted | ) |
|
|
inline |
Sets the number of items completed.
- Precondition
- The new number of items completed is non-negative.
-
If the expected total is non-negative, then the new number of items completed is at most the expected total.
- Parameters
-
newCompleted | the number of items completed. |
void regina::NProgress::setFinished |
( |
| ) |
|
|
inlineinherited |
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.
void regina::NProgressNumber::setOutOf |
( |
long |
newOutOf | ) |
|
|
inline |
Sets the expected total number of items.
- Precondition
- If the new expected total is non-negative, then the new expected total is at least the number of items completed.
- Parameters
-
newOutOf | the expected total number of items, or -1 if this total is not known. |
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 |
|
inlineinherited |
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 |
|
inlineinherited |
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.
long regina::NProgress::totalCPUTime |
( |
| ) |
const |
|
inlineinherited |
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::ShareableObject::writeTextLong |
( |
std::ostream & |
out | ) |
const |
|
inlinevirtualinherited |
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::NProgress::writeTextShort |
( |
std::ostream & |
out | ) |
const |
|
inlinevirtualinherited |
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.
bool regina::NProgress::cancelled |
|
protectedinherited |
Has this operation been cancelled?
bool regina::NProgress::changed |
|
mutableprotectedinherited |
Has the state of progress changed since the last query?
The documentation for this class was generated from the following file: