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:

Public Member Functions
Preparation methods
auxiliary type for passing NULL name to Message_ProgressScope constructor Creates dummy scope. It can be safely passed to algorithms; no progress indication will be done.
	Message_ProgressScope ()
	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.
	Message_ProgressScope (const Message_ProgressRange &theRange, const TCollection_AsciiString &theName, double theMax, bool 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.
template<size_t N>
	Message_ProgressScope (const Message_ProgressRange &theRange, const char(&theName)[N], double theMax, bool 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.
	Message_ProgressScope (const Message_ProgressRange &theRange, const NullString *theName, double theMax, bool 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.
void	SetName (const TCollection_AsciiString &theName)
	Sets the name of the scope.
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.
Advance by iterations
Returns true if ProgressIndicator signals UserBreak
bool	UserBreak () const
	Returns false if ProgressIndicator signals UserBreak.
bool	More () const
	Returns false if ProgressIndicator signals UserBreak.
Message_ProgressRange	Next (double theStep=1.)
	Advances position by specified step and returns the range covering this step.
Auxiliary methods to use in ProgressIndicator
Force update of presentation of the progress indicator. Should not be called concurrently.
void	Show ()
	Returns true if this progress scope is attached to some indicator.
bool	IsActive () const
	Returns true if this progress scope is attached to some indicator.
const char *	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.
const Message_ProgressScope *	Parent () const
	Returns parent scope (null for top-level scope).
double	MaxValue () const
	Returns the maximal value of progress in this scope.
double	Value () const
	Returns the current value of progress in this scope.
bool	IsInfinite () const
	Returns the infinite flag.
double	GetPortion () const
	Get the portion of the indicator covered by this scope (from 0 to 1).
Destruction, allocation
Destructor - closes the scope and adds its scale to the total progress
	~Message_ProgressScope ()
	Closes the scope and advances the progress to its end. Closed scope should not be used.
void	Close ()
	Closes the scope and advances the progress to its end. Closed scope should not be used.

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 double (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:

occ::handle<Message_ProgressIndicator> aProgress = ...; // assume it can be null
func (Message_ProgressIndicator::Start (aProgress));

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 (int i = 0; i < nbOuter && anOuter.More(); i++)
{
  // Inner cycle
  Message_ProgressScope anInner (anOuter.Next(), "Inner", nbInner);
  for (int 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 (int 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;
  Message_ProgressRange Range;
 
  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 (int 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 (int 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 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

[in]

out] theRange range to fill (will be disarmed)

Parameters

[in]	theName	new scope name
[in]	theMax	number of steps in scope
[in]	isInfinite	infinite flag

Message_ProgressScope() [2/4]

Message_ProgressScope::Message_ProgressScope ( const Message_ProgressRange & theRange, const TCollection_AsciiString & theName, double theMax, bool 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

[in]

out] theRange range to fill (will be disarmed)

Parameters

[in]	theName	new scope name
[in]	theMax	number of steps in scope
[in]	isInfinite	infinite flag

Message_ProgressScope() [3/4]

template<size_t N>

Message_ProgressScope::Message_ProgressScope	(	const Message_ProgressRange &	theRange,
		const char(&)	theName[N],
		double	theMax,
		bool	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

[in]

out] theRange range to fill (will be disarmed)

Parameters

[in]	theName	new scope name constant (will be stored by pointer with no deep copy)
[in]	theMax	number of steps in scope
[in]	isInfinite	infinite flag

Message_ProgressScope() [4/4]

Message_ProgressScope::Message_ProgressScope ( const Message_ProgressRange & theRange, const NullString * theName, double theMax, bool 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

[in]

out] theRange range to fill (will be disarmed)

Parameters

[in]	theName	empty scope name (only NULL is accepted as argument)
[in]	theMax	number of steps in scope
[in]	isInfinite	infinite flag

~Message_ProgressScope()

Message_ProgressScope::~Message_ProgressScope ( )

inline

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

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

double Message_ProgressScope::GetPortion ( ) const

inline

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

IsActive()

bool Message_ProgressScope::IsActive ( ) const

inline

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

IsInfinite()

bool Message_ProgressScope::IsInfinite ( ) const

inline

Returns the infinite flag.

MaxValue()

double Message_ProgressScope::MaxValue ( ) const

inline

Returns the maximal value of progress in this scope.

More()

bool Message_ProgressScope::More ( ) const

inline

Returns false if ProgressIndicator signals UserBreak.

Name()

const char * 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 ( double 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]

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.

SetName() [2/2]

void Message_ProgressScope::SetName ( const TCollection_AsciiString & theName )

inline

Sets the name of the scope.

Show()

void Message_ProgressScope::Show ( )

inline

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

UserBreak()

bool Message_ProgressScope::UserBreak ( ) const

inline

Returns false if ProgressIndicator signals UserBreak.

Value()

double Message_ProgressScope::Value ( ) 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:

• Message_ProgressScope.hxx