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
	Message_ProgressScope ()
	Creates dummy scope. It can be safely passed to algorithms; no progress indication will be done.
	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.
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.
	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.
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
Standard_Boolean	UserBreak () const
	Returns true if ProgressIndicator signals UserBreak.
Standard_Boolean	More () const
	Returns false if ProgressIndicator signals UserBreak.
Message_ProgressRange	Next (Standard_Real theStep=1.)
	Advances position by specified step and returns the range covering this step.
Auxiliary methods to use in ProgressIndicator
void	Show ()
	Force update of presentation of the progress indicator. Should not be called concurrently.
Standard_Boolean	IsActive () const
	Returns true if this progress scope is attached to some indicator.
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.
const Message_ProgressScope *	Parent () const
	Returns parent scope (null for top-level scope)
Standard_Real	MaxValue () const
	Returns the maximal value of progress in this scope.
Standard_Real	Value () const
	Returns the current value of progress in this scope.
Standard_Boolean	IsInfinite () const
	Returns the infinite flag.
Standard_Real	GetPortion () const
	Get the portion of the indicator covered by this scope (from 0 to 1)
Destruction, allocation
	~Message_ProgressScope ()
	Destructor - closes the scope and adds its scale to the total progress.
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 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
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 (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;
  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 (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 ( ) 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]

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

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