Defines abstract interface from program to the user. This includes progress indication and user break mechanisms. More...

#include <Message_ProgressIndicator.hxx>

Inheritance diagram for Message_ProgressIndicator:

[legend]

Protected Member Functions
Virtual methods to be defined by descendant.
virtual bool	UserBreak ()
	Should return True if user has sent a break signal.

virtual void	Show (const Message_ProgressScope &theScope, const bool isForce)=0
	Virtual method to be defined by descendant. Should update presentation of the progress indicator.

virtual void	Reset ()
	Call-back method called by Start(), can be redefined by descendants if some actions are needed when the indicator is restarted.

Auxiliary methods
double	GetPosition () const
	Returns total progress position ranged from 0 to 1. Should not be called concurrently while the progress is advancing, except from implementation of method Show().

	~Message_ProgressIndicator () override
	Destructor.

	Message_ProgressIndicator ()
	Constructor.

Initialization of progress indication
Message_ProgressRange	Start ()
	Resets the indicator to zero, calls Reset(), and returns the range. This range refers to the scope that has no name and is initialized with max value 1 and step 1. Use this method to get the top level range for progress indication.

static Message_ProgressRange	Start (const occ::handle< Message_ProgressIndicator > &theProgress)
	If argument is non-null handle, returns theProgress->Start(). Otherwise, returns dummy range that can be safely used in the algorithms but not bound to progress indicator.

Additional Inherited Members
Public Types inherited from Standard_Transient
typedef void	base_type
	Returns a type descriptor about this object.

Public Member Functions inherited from Standard_Transient
	Standard_Transient ()
	Empty constructor.

	Standard_Transient (const Standard_Transient &)
	Copy constructor – does nothing.

Standard_Transient &	operator= (const Standard_Transient &)
	Assignment operator, needed to avoid copying reference counter.

virtual	~Standard_Transient ()=default
	Destructor must be virtual.

virtual const opencascade::handle< Standard_Type > &	DynamicType () const
	Returns a type descriptor about this object.

bool	IsInstance (const opencascade::handle< Standard_Type > &theType) const
	Returns a true value if this is an instance of Type.

bool	IsInstance (const char *const theTypeName) const
	Returns a true value if this is an instance of TypeName.

bool	IsKind (const opencascade::handle< Standard_Type > &theType) const
	Returns true if this is an instance of Type or an instance of any class that inherits from Type. Note that multiple inheritance is not supported by OCCT RTTI mechanism.

bool	IsKind (const char *const theTypeName) const
	Returns true if this is an instance of TypeName or an instance of any class that inherits from TypeName. Note that multiple inheritance is not supported by OCCT RTTI mechanism.

Standard_Transient *	This () const
	Returns non-const pointer to this object (like const_cast). For protection against creating handle to objects allocated in stack or call from constructor, it will raise exception Standard_ProgramError if reference counter is zero.

int	GetRefCount () const noexcept
	Get the reference counter of this object.

void	IncrementRefCounter () noexcept
	Increments the reference counter of this object. Uses relaxed memory ordering since incrementing only requires atomicity, not synchronization with other memory operations.

int	DecrementRefCounter () noexcept
	Decrements the reference counter of this object; returns the decremented value. Uses release ordering for the decrement to ensure all writes to the object are visible before the count reaches zero. An acquire fence is added only when the count reaches zero, ensuring proper synchronization before deletion. This is more efficient than using acq_rel for every decrement.

virtual void	Delete () const
	Memory deallocator for transient classes.

Static Public Member Functions inherited from Standard_Transient
static constexpr const char *	get_type_name ()
	Returns a type descriptor about this object.

static const opencascade::handle< Standard_Type > &	get_type_descriptor ()
	Returns type descriptor of Standard_Transient class.

Detailed Description

Defines abstract interface from program to the user. This includes progress indication and user break mechanisms.

The progress indicator controls the progress scale with range from 0 to 1.

Method Start() should be called once, at the top level of the call stack, to reset progress indicator and get access to the root range:

occ::handle<Message_ProgressIndicator> aProgress = ...;

anAlgorithm.Perform (aProgress->Start());

NCollection_ForwardRangeIterator

STL input iterator that wraps an OCCT More()/Next() iterator.

Definition NCollection_ForwardRange.hxx:142

opencascade::handle

Intrusive smart pointer for use with Standard_Transient class and its descendants.

Definition Standard_Handle.hxx:54

To advance the progress indicator in the algorithm, use the class Message_ProgressScope that provides iterator-like interface for incrementing progress; see documentation of that class for details. The object of class Message_ProgressRange will automatically advance the indicator if it is not passed to any Message_ProgressScope.

The progress indicator supports concurrent processing and can be used in multithreaded applications.

The derived class should be created to connect this interface to actual implementation of progress indicator, to take care of visualization of the progress (e.g. show total position at the graphical bar, print scopes in text mode, or else), and for implementation of user break mechanism (if necessary).

See details in documentation of methods Show() and UserBreak().

Constructor & Destructor Documentation

◆ ~Message_ProgressIndicator()

Message_ProgressIndicator::~Message_ProgressIndicator ( )

override

Destructor.

◆ Message_ProgressIndicator()

Message_ProgressIndicator::Message_ProgressIndicator ( )

protected

Constructor.

Member Function Documentation

◆ GetPosition()

double Message_ProgressIndicator::GetPosition ( ) const

inline

Returns total progress position ranged from 0 to 1. Should not be called concurrently while the progress is advancing, except from implementation of method Show().

◆ Reset()

virtual void Message_ProgressIndicator::Reset ( )

inlineprotectedvirtual

Call-back method called by Start(), can be redefined by descendants if some actions are needed when the indicator is restarted.

Reimplemented in Draw_ProgressIndicator.

◆ Show()

virtual void Message_ProgressIndicator::Show	(	const Message_ProgressScope &	theScope,
		const bool	isForce )

protectedpure virtual

Virtual method to be defined by descendant. Should update presentation of the progress indicator.

It is called whenever progress position is changed. Calls to this method from progress indicator are protected by mutex so that it is never called concurrently for the same progress indicator instance. Show() should return as soon as possible to reduce thread contention in multithreaded algorithms.

It is recommended to update (redraw, output etc.) only if progress is advanced by at least 1% from previous update.

Flag isForce is intended for forcing update in case if it is required at particular step of the algorithm; all calls to it from inside the core mechanism (Message_Progress... classes) are done with this flag equal to False.

The parameter theScope is the current scope being advanced; it can be used to show the names and ranges of the on-going scope and its parents, providing more visibility of the current stage of the process.

Implemented in Draw_ProgressIndicator.

◆ Start() [1/2]

Message_ProgressRange Message_ProgressIndicator::Start ( )

Resets the indicator to zero, calls Reset(), and returns the range. This range refers to the scope that has no name and is initialized with max value 1 and step 1. Use this method to get the top level range for progress indication.

◆ Start() [2/2]

static Message_ProgressRange Message_ProgressIndicator::Start ( const occ::handle< Message_ProgressIndicator > & theProgress )

static

If argument is non-null handle, returns theProgress->Start(). Otherwise, returns dummy range that can be safely used in the algorithms but not bound to progress indicator.

◆ UserBreak()

virtual bool Message_ProgressIndicator::UserBreak ( )

inlineprotectedvirtual

Should return True if user has sent a break signal.

This method can be called concurrently, thus implementation should be thread-safe. It should not call Show() or Position() to avoid possible data races. The method should return as soon as possible to avoid delaying the calling algorithm.

Default implementation returns False.