Open CASCADE Technology  7.7.0
Message_ProgressScope Class Reference

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>

Inheritance diagram for Message_ProgressScope:
Inheritance graph
[legend]

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

Detailed Description

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:

Handle(Message_ProgressIndicator) aProgress = ...; // assume it can be null

Example of usage in sequential process:

Message_ProgressScope aWholePS(aRange, "Whole process", 100);
// do one step taking 20%
func1 (aWholePS.Next (20)); // func1 will take 20% of the whole scope
if (aWholePS.UserBreak()) // exit prematurely if the user requested break
return;
// ... do next step taking 50%
func2 (aWholePS.Next (50));
if (aWholePS.UserBreak())
return;

Example of usage in nested cycle:

// Outer cycle
Message_ProgressScope anOuter (theProgress, "Outer", nbOuter);
for (Standard_Integer i = 0; i < nbOuter && anOuter.More(); i++)
{
// Inner cycle
Message_ProgressScope anInner (anOuter.Next(), "Inner", nbInner);
for (Standard_Integer j = 0; j < nbInner && anInner.More(); j++)
{
// Cycle body
func (anInner.Next());
}
}

Example of use in function:

func (const Message_ProgressRange& theProgress)
{
// Create local scope covering the given progress range.
// Set this scope to count aNbSteps steps.
Message_ProgressScope aScope (theProgress, "", aNbSteps);
for (Standard_Integer i = 0; i < aNbSteps && aScope.More(); i++)
{
// Optional: pass range returned by method Next() to the nested algorithm
// to allow it to show its progress too (by creating its own scope object).
// In any case the progress will advance to the next step by the end of the func2 call.
func2 (aScope.Next());
}
}

Example of usage in parallel process:

struct Task
{
Data& Data;
Task (const Data& theData, const Message_ProgressRange& theRange)
: Data (theData), Range (theRange) {}
};
struct Functor
{
void operator() (Task& theTask) const
{
// Note: it is essential that this method is executed only once for the same Task object
Message_ProgressScope aPS (theTask.Range, NULL, theTask.Data.NbItems);
for (Standard_Integer i = 0; i < theTask.Data.NbSteps && aPS.More(); i++)
{
do_job (theTask.Data.Item[i], aPS.Next());
}
}
};
...
{
std::vector<Data> aData = ...;
std::vector<Task> aTasks;
Message_ProgressScope aPS (aRootRange, "Data processing", aData.size());
for (Standard_Integer i = 0; i < aData.size(); ++i)
aTasks.push_back (Task (aData[i], aPS.Next()));
OSD_Parallel::ForEach (aTasks.begin(), aTasks.end(), Functor());
}

For lightweight algorithms that do not need advancing the progress within individual tasks the code can be simplified to avoid inner scopes:

struct Functor
{
void operator() (Task& theTask) const
{
if (theTask.Range.More())
{
do_job (theTask.Data);
// advance the progress
theTask.Range.Close();
}
}
};

Constructor & Destructor Documentation

◆ Message_ProgressScope() [1/4]

Message_ProgressScope::Message_ProgressScope ( )
inline

Creates dummy scope. It can be safely passed to algorithms; no progress indication will be done.

◆ Message_ProgressScope() [2/4]

Message_ProgressScope::Message_ProgressScope ( const Message_ProgressRange theRange,
const TCollection_AsciiString theName,
Standard_Real  theMax,
Standard_Boolean  isInfinite = false 
)
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.

Parameters
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() [3/4]

template<size_t N>
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.

Parameters
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

◆ Message_ProgressScope() [4/4]

Message_ProgressScope::Message_ProgressScope ( const Message_ProgressRange theRange,
const NullString *  theName,
Standard_Real  theMax,
Standard_Boolean  isInfinite = false 
)
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.

Parameters
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

◆ ~Message_ProgressScope()

Message_ProgressScope::~Message_ProgressScope ( )
inline

Destructor - closes the scope and adds its scale to the total progress.

Member Function Documentation

◆ Close()

void Message_ProgressScope::Close ( )
inline

Closes the scope and advances the progress to its end. Closed scope should not be used.

◆ GetPortion()

Standard_Real Message_ProgressScope::GetPortion ( ) const
inline

Get the portion of the indicator covered by this scope (from 0 to 1)

◆ IsActive()

Standard_Boolean Message_ProgressScope::IsActive ( ) const
inline

Returns true if this progress scope is attached to some indicator.

◆ IsInfinite()

Standard_Boolean Message_ProgressScope::IsInfinite ( ) const
inline

Returns the infinite flag.

◆ MaxValue()

Standard_Real Message_ProgressScope::MaxValue ( ) const
inline

Returns the maximal value of progress in this scope.

◆ More()

Standard_Boolean Message_ProgressScope::More ( void  ) const
inline

Returns false if ProgressIndicator signals UserBreak.

◆ Name()

Standard_CString Message_ProgressScope::Name ( ) const
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.

◆ Next()

Message_ProgressRange Message_ProgressScope::Next ( Standard_Real  theStep = 1.)
inline

Advances position by specified step and returns the range covering this step.

◆ Parent()

const Message_ProgressScope* Message_ProgressScope::Parent ( ) const
inline

Returns parent scope (null for top-level scope)

◆ SetName() [1/2]

void Message_ProgressScope::SetName ( const TCollection_AsciiString theName)
inline

Sets the name of the scope.

◆ SetName() [2/2]

template<size_t N>
void Message_ProgressScope::SetName ( const char(&)  theName[N])
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.

◆ Show()

void Message_ProgressScope::Show ( )
inline

Force update of presentation of the progress indicator. Should not be called concurrently.

◆ UserBreak()

Standard_Boolean Message_ProgressScope::UserBreak ( ) const
inline

Returns true if ProgressIndicator signals UserBreak.

◆ Value()

Standard_Real Message_ProgressScope::Value ( void  ) const
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.


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