Provides progress status and notification mechanism. More...

#include <cadex/Base/ProgressStatus.hxx>

Inheritance diagram for cadex::ProgressStatus:

Classes
class	CancellationChecker
	Base abstract class for cancelation checker registered in ProgressStatus. More...

class	Observer
	Base abstract class for observers registered in ProgressStatus. More...

Public Member Functions
	ProgressStatus ()
	Constructor.

double	Value () const
	Returns a current value.

void	Register (Observer &theObserver, double theValueThreshold=0.1f, unsigned int theTimeThreshold=20U)
	Adds an observer that will be notified when the progress status has changed.

void	Unregister (const Observer &theObserver)
	Removes a previously added observer.

void	SetObserversNotifyingThread ()
	Sets the current thread as the only thread sending notifications for all registered observers.

void	SetCancellationChecker (const CancellationChecker &theChecker)
	Sets the cancellation checker.

void	RemoveCancellationChecker ()
	Removes the cancellation checker.

void	Cancel ()
	A callback called when the progress status object was set to the canceled state.

bool	WasCanceled () const
	Returns true if the operation has been canceled.

Public Member Functions inherited from cadex::BaseObject
size_t	Id () const
	Return unique identifier of public object.

internal::BaseObjectImpl *	Impl () const

bool	IsNull () const

	operator bool () const

template<typename T >
bool	IsOfType () const

template<typename T >
T *	Impl () const
	Reserved for internal use.

Static Public Member Functions
static double	MinValue ()
	Returns a minimum value of the progress status.

static double	MaxValue ()
	Returns a maximum value of the progress status.

Additional Inherited Members
Public Types inherited from cadex::BaseObject
typedef std::shared_ptr< internal::BaseObjectImpl >	ImplType

Protected Member Functions inherited from cadex::BaseObject
	BaseObject (const ImplType &theImpl)

Detailed Description

Provides progress status and notification mechanism.

ProgressStatus has a current Value() which belongs to the range [0, 100]. The algorithms that support progress status update increment this value during their execution.

Upon value change the status object notifies its observers (subclasses of the ProgressStatus::Observer class) registered with the Register() method. Thus, it implements the observer design pattern. The life span of the observer must be greater than the life span of the status object.

In the case there are no observers, the progress status incurs minimum overhead to the algorithm.

The status objects can be assigned to each other to create a chained range shared by several algorithms.

ProgressScope objects can be used to split progress status range into smaller scopes. The scopes can be nested.

For details refer to Progress Status Support section.

Member Function Documentation

◆ Cancel()

void cadex::ProgressStatus::Cancel ( )

A callback called when the progress status object was set to the canceled state.

This callback is called when ProgressStatus::Cancel() was called. Default implementation is empty.

◆ MaxValue()

static double cadex::ProgressStatus::MaxValue ( )

inlinestatic

Returns a maximum value of the progress status.

By convention, returns 100.

◆ MinValue()

static double cadex::ProgressStatus::MinValue ( )

inlinestatic

Returns a minimum value of the progress status.

By convention, returns 0.

◆ Register()

void cadex::ProgressStatus::Register	(	ProgressStatus::Observer &	theObserver,
		double	theValueThreshold = 0.1f,
		unsigned int	theTimeThreshold = 20U )

Adds an observer that will be notified when the progress status has changed.

The life span of theObserver must be greater than one of this status object. If this cannot be guaranteed then the observer must be removed using the Unregister() method.

Registered observers will receive notification of a new value of this status object if the both following conditions are true:

the difference between a value used in previous notification is equal to or greater than theValueThreshold and
the time passed since previous notification is equal to or greater theTimeThreshold (specified in milliseconds).

Changing these thresholds you can manipulate frequency of the notifications for each observer.

See also: Unregister().

◆ RemoveCancellationChecker()

void cadex::ProgressStatus::RemoveCancellationChecker ( )

Removes the cancellation checker.

Removes a checker set in SetCancellationChecker().

◆ SetCancellationChecker()

void cadex::ProgressStatus::SetCancellationChecker ( const CancellationChecker & theChecker )

Sets the cancellation checker.

The life span of theChecker must be greater than of this object (because internally only a pointer to theChecker is stored).

See also: RemoveCancellationChecker().

◆ SetObserversNotifyingThread()

void cadex::ProgressStatus::SetObserversNotifyingThread ( )

Sets the current thread as the only thread sending notifications for all registered observers.

Can be used in situations where the thread only has access to progress status but not its observers.

◆ Unregister()

void cadex::ProgressStatus::Unregister ( const Observer & theObserver )

Removes a previously added observer.

See also: Register().

◆ Value()

double cadex::ProgressStatus::Value ( ) const

Returns a current value.

The values is in the range [0, 100].

Beware of internal rounding errors. You might want to round the returned value to get a required precision for more confident usage.

◆ WasCanceled()

bool cadex::ProgressStatus::WasCanceled ( ) const

Returns true if the operation has been canceled.

The operation can be canceled either by explicit call to Cancel() or when a cancelation checker set with SetCancellationChecker() returned true.

See also: Cancel().

Classes

Public Member Functions

Static Public Member Functions

Additional Inherited Members