Open CASCADE Technology
7.7.0
|
Message_ProgressScope class provides convenient way to advance progress indicator in context of complex program organized in hierarchical way, where usually it is difficult (or even not possible) to consider process as linear with fixed step. More...
#include <Message_ProgressScope.hxx>
Public Member Functions | |
Preparation methods | |
auxiliary type for passing NULL name to Message_ProgressScope constructor | |
Message_ProgressScope () | |
Creates dummy scope. It can be safely passed to algorithms; no progress indication will be done. More... | |
Message_ProgressScope (const Message_ProgressRange &theRange, const TCollection_AsciiString &theName, Standard_Real theMax, Standard_Boolean isInfinite=false) | |
Creates a new scope taking responsibility of the part of the progress scale described by theRange. The new scope has own range from 0 to theMax, which is mapped to the given range. More... | |
template<size_t N> | |
Message_ProgressScope (const Message_ProgressRange &theRange, const char(&theName)[N], Standard_Real theMax, Standard_Boolean isInfinite=false) | |
Creates a new scope taking responsibility of the part of the progress scale described by theRange. The new scope has own range from 0 to theMax, which is mapped to the given range. More... | |
Message_ProgressScope (const Message_ProgressRange &theRange, const NullString *theName, Standard_Real theMax, Standard_Boolean isInfinite=false) | |
Creates a new scope taking responsibility of the part of the progress scale described by theRange. The new scope has own range from 0 to theMax, which is mapped to the given range. More... | |
void | SetName (const TCollection_AsciiString &theName) |
Sets the name of the scope. More... | |
template<size_t N> | |
void | SetName (const char(&theName)[N]) |
Sets the name of the scope; can be null. Note! Just pointer to the given string is copied, so do not pass string from a temporary variable whose lifetime is less than that of this object. More... | |
Advance by iterations | |
Standard_Boolean | UserBreak () const |
Returns true if ProgressIndicator signals UserBreak. More... | |
Standard_Boolean | More () const |
Returns false if ProgressIndicator signals UserBreak. More... | |
Message_ProgressRange | Next (Standard_Real theStep=1.) |
Advances position by specified step and returns the range covering this step. More... | |
Auxiliary methods to use in ProgressIndicator | |
void | Show () |
Force update of presentation of the progress indicator. Should not be called concurrently. More... | |
Standard_Boolean | IsActive () const |
Returns true if this progress scope is attached to some indicator. More... | |
Standard_CString | Name () const |
Returns the name of the scope (may be null). Scopes with null name (e.g. root scope) should be bypassed when reporting progress to the user. More... | |
const Message_ProgressScope * | Parent () const |
Returns parent scope (null for top-level scope) More... | |
Standard_Real | MaxValue () const |
Returns the maximal value of progress in this scope. More... | |
Standard_Real | Value () const |
Returns the current value of progress in this scope. More... | |
Standard_Boolean | IsInfinite () const |
Returns the infinite flag. More... | |
Standard_Real | GetPortion () const |
Get the portion of the indicator covered by this scope (from 0 to 1) More... | |
Destruction, allocation | |
~Message_ProgressScope () | |
Destructor - closes the scope and adds its scale to the total progress. More... | |
void | Close () |
Closes the scope and advances the progress to its end. Closed scope should not be used. More... | |
Message_ProgressScope class provides convenient way to advance progress indicator in context of complex program organized in hierarchical way, where usually it is difficult (or even not possible) to consider process as linear with fixed step.
On every level (sub-operation) in hierarchy of operations the local instance of the Message_ProgressScope class is created. It takes a part of the upper-level scope (via Message_ProgressRange) and provides a way to consider this part as independent scale with locally defined range.
The position on the local scale may be advanced using the method Next(), which allows iteration-like advancement. This method can take argument to advance by the specified value (with default step equal to 1). This method returns Message_ProgressRange object that takes responsibility of making the specified step, either directly at its destruction or by delegating this task to another sub-scope created from that range object.
It is important that sub-scope must have life time less than the life time of its parent scope that provided the range. The usage pattern is to create scope objects as local variables in the functions that do the job, and pass range objects returned by Next() to the functions of the lower level, to allow them creating their own scopes.
The scope has a name that can be used in visualization of the progress. It can be null. Note that when C string literal is used as a name, then its value is not copied, just pointer is stored. In other variants (char pointer or a string class) the string is copied, which is additional overhead.
The same instance of the progress scope! must not be used concurrently from different threads. For the algorithm running its tasks in parallel threads, a common scope is created before the parallel execution, and the range objects produced by method Next() are used to initialise the data pertinent to each task. Then the progress is advanced within each task using its own range object. See example below.
Note that while a range of the scope is specified using Standard_Real (double) parameter, it is expected to be a positive integer value. If the range is not an integer, method Next() shall be called with explicit step argument, and the rounded value returned by method Value() may be not coherent with the step and range.
A scope can be created with option "infinite". This is useful when the number of steps is not known by the time of the scope creation. In this case the progress will be advanced logarithmically, approaching the end of the scope at infinite number of steps. The parameter Max for infinite scope indicates number of steps corresponding to mid-range.
A progress scope created with empty constructor is not connected to any progress indicator, and passing the range created on it to any algorithm allows it executing safely without actual progress indication.
Example of preparation of progress indicator:
Example of usage in sequential process:
Example of usage in nested cycle:
Example of use in function:
Example of usage in parallel process:
For lightweight algorithms that do not need advancing the progress within individual tasks the code can be simplified to avoid inner scopes:
|
inline |
Creates dummy scope. It can be safely passed to algorithms; no progress indication will be done.
|
inline |
Creates a new scope taking responsibility of the part of the progress scale described by theRange. The new scope has own range from 0 to theMax, which is mapped to the given range.
The topmost scope is created and owned by Message_ProgressIndicator and its pointer is contained in the Message_ProgressRange returned by the Start() method of progress indicator.
theRange | [in][out] range to fill (will be disarmed) |
theName | [in] new scope name |
theMax | [in] number of steps in scope |
isInfinite | [in] infinite flag |
Message_ProgressScope::Message_ProgressScope | ( | const Message_ProgressRange & | theRange, |
const char(&) | theName[N], | ||
Standard_Real | theMax, | ||
Standard_Boolean | isInfinite = false |
||
) |
Creates a new scope taking responsibility of the part of the progress scale described by theRange. The new scope has own range from 0 to theMax, which is mapped to the given range.
The topmost scope is created and owned by Message_ProgressIndicator and its pointer is contained in the Message_ProgressRange returned by the Start() method of progress indicator.
theRange | [in][out] range to fill (will be disarmed) |
theName | [in] new scope name constant (will be stored by pointer with no deep copy) |
theMax | [in] number of steps in scope |
isInfinite | [in] infinite flag |
|
inline |
Creates a new scope taking responsibility of the part of the progress scale described by theRange. The new scope has own range from 0 to theMax, which is mapped to the given range.
The topmost scope is created and owned by Message_ProgressIndicator and its pointer is contained in the Message_ProgressRange returned by the Start() method of progress indicator.
theRange | [in][out] range to fill (will be disarmed) |
theName | [in] empty scope name (only NULL is accepted as argument) |
theMax | [in] number of steps in scope |
isInfinite | [in] infinite flag |
|
inline |
Destructor - closes the scope and adds its scale to the total progress.
|
inline |
Closes the scope and advances the progress to its end. Closed scope should not be used.
|
inline |
Get the portion of the indicator covered by this scope (from 0 to 1)
|
inline |
Returns true if this progress scope is attached to some indicator.
|
inline |
Returns the infinite flag.
|
inline |
Returns the maximal value of progress in this scope.
|
inline |
Returns false if ProgressIndicator signals UserBreak.
|
inline |
Returns the name of the scope (may be null). Scopes with null name (e.g. root scope) should be bypassed when reporting progress to the user.
|
inline |
Advances position by specified step and returns the range covering this step.
|
inline |
Returns parent scope (null for top-level scope)
|
inline |
Sets the name of the scope.
|
inline |
Sets the name of the scope; can be null. Note! Just pointer to the given string is copied, so do not pass string from a temporary variable whose lifetime is less than that of this object.
|
inline |
Force update of presentation of the progress indicator. Should not be called concurrently.
|
inline |
Returns true if ProgressIndicator signals UserBreak.
|
inline |
Returns the current value of progress in this scope.
The value is computed by mapping current global progress into this scope range; the result is rounded up to integer. Note that if MaxValue() is not an integer, Value() can be greater than MaxValue() due to that rounding.
This method should not be called concurrently while the progress is advancing, except from implementation of method Show() in descendant of Message_ProgressIndicator.