An asynchronous status monitoring system. More...

#include <StatusMonitor.h>

Public Member Functions
	StatusMonitor ()=default

	StatusMonitor (const StatusMonitor &x)

virtual	~StatusMonitor ()

StatusCallback *	Callback ()

const StatusCallback *	Callback () const

void	Clear ()

void	Complete ()

size_type	Count () const

void	DisableInitialization ()

void	EnableInitialization ()

String	Info () const

void	Initialize (const String &info, size_type count=0)

bool	IsAborted () const

bool	IsCompleted () const

bool	IsInitializationEnabled () const

bool	IsInitialized () const

void	operator++ ()

void	operator+= (size_type n)

StatusMonitor &	operator= (const StatusMonitor &x)

int	ReturnValue () const

void	SetCallback (StatusCallback *callback)

void	SetInfo (const String &s)

size_type	Total () const

Static Public Member Functions
static unsigned	RefreshRate ()

static void	SetRefreshRate (unsigned ms)

Detailed Description

Status monitoring consists of a set of PCL classes and functions to manage progress information about ongoing processes. A status monitor is an instance of the StatusMonitor class.

Status monitors provide a generalized mechanism to generate and manage progress information while a process is running. A status monitor sends progress events to an instance of a StatusCallback subclass, whose primary responsibility is to provide feedback to the user. Progress feedback typically consists of a running percentage or similar text-based information written to the standard console.

Along with providing progress feedback, the status monitoring concept is quite flexible and has other control applications in PCL, some of them quite sophisticated. For example, many standard tools use specialized status monitors to implement their real-time preview routines as asynchronously interruptible processes.

StatusMonitor utilizes a low-priority timing thread to generate callback monitoring calls asynchronously at constant time intervals. This has virtually zero impact on the performance of the monitored processes.

See also: StatusCallback, StandardStatus, SpinStatus, MuteStatus, Console, Thread

Definition at line 222 of file StatusMonitor.h.

Constructor & Destructor Documentation

◆ StatusMonitor() [1/2]

pcl::StatusMonitor::StatusMonitor ( )

default

Constructs a default StatusMonitor object.

◆ StatusMonitor() [2/2]

pcl::StatusMonitor::StatusMonitor ( const StatusMonitor & x )

inline

Copy constructor.

Definition at line 234 of file StatusMonitor.h.

◆ ~StatusMonitor()

virtual pcl::StatusMonitor::~StatusMonitor ( )

inlinevirtual

Virtual destructor.

Definition at line 242 of file StatusMonitor.h.

Member Function Documentation

◆ Callback() [1/2]

StatusCallback* pcl::StatusMonitor::Callback ( )

inline

Returns the address of the status callback object associated with this status monitor. Returns zero if this monitor has no associated status callback object.

Definition at line 484 of file StatusMonitor.h.

◆ Callback() [2/2]

const StatusCallback* pcl::StatusMonitor::Callback ( ) const

inline

Returns the address of the immutable status callback object associated with this status monitor. Returns zero if this monitor has no associated status callback object.

Definition at line 474 of file StatusMonitor.h.

◆ Clear()

void pcl::StatusMonitor::Clear ( )

inline

Interrupts the current monitoring procedure, if any, and reinitializes the internal state of this status monitor.

Definition at line 556 of file StatusMonitor.h.

◆ Complete()

void pcl::StatusMonitor::Complete ( )

inline

Forces this monitor to complete the current monitoring procedure, by assigning the total progress count to the progress counter.

This function forces a call to StatusCallback::Completed(), if this monitor has an associated status callback object.

Definition at line 463 of file StatusMonitor.h.

◆ Count()

size_type pcl::StatusMonitor::Count ( ) const

inline

Returns the progress counter for the current monitoring procedure.

When the progress counter reaches the total count, the monitoring procedure has been completed.

Definition at line 536 of file StatusMonitor.h.

Referenced by pcl::RealTimeProgressStatus::Updated().

◆ DisableInitialization()

void pcl::StatusMonitor::DisableInitialization ( )

inline

Increments the initialization disabling counter for this status monitor.

When the disabling counter is greater than zero, initialization is disabled for this monitor, and subsequent calls to the Initialize() member function have no effect.

This is useful if your process calls other subroutines that try to initialize private monitoring procedures. If such subroutines are called as independent processes, they can perform initialization, but if they are used as part of a higher level process, they should update a common status monitor without reinitializing it.

Here is an example:

FunctionA( StatusMonitor& m )
{
   if ( m.IsInitializationEnabled() )
      m.Initialize( "This is function A...", 100 );
   // ...
   for ( int i = 0; i < 100; ++i, ++m )
      // ...
}
 
FunctionB( StatusMonitor& m )
{
   if ( m.IsInitializationEnabled() )
      m.Initialize( "This is function B...", 100 );
   // ...
   for ( int i = 0; i < 10; ++i, m += 10 )
      // ...
}
 
ALargerFunction( StatusMonitor& m )
{
   m.Initialize( "This is some high-level routine...", 200 );
   m.DisableInitialization();
   // ...
   FunctionA( m );
   FunctionB( m );
   // ...
   m.EnableInitialization();
}

In this example, both FunctionA() and FunctionB() update a StatusMonitor object by a total count of 100 steps. However, these functions don't try to initialize the passed monitor if initialization has been disabled.

ALargerFunction() initializes a status monitor with a total count of 200 and its own information string, then disables monitor initialization. The subsequent calls to FunctionA() and FunctionB() will update the monitor by 100 steps each, without reinitializing it.

The final call to EnableInitialization() in ALargerFunction() is necessary to return the status monitor to its initial enabled or disabled state.

Definition at line 337 of file StatusMonitor.h.

◆ EnableInitialization()

void pcl::StatusMonitor::EnableInitialization ( )

inline

Decrements the initialization disabling counter for this status monitor.

When the disabling counter is equal or less than zero, initialization is enabled for this monitor.

See DisableInitialization() for further information on the initialization enabled/disabled states and a source code example.

Definition at line 351 of file StatusMonitor.h.

◆ Info()

String pcl::StatusMonitor::Info ( ) const

inline

Returns the progress information string that has been set for this status monitor object.

Definition at line 525 of file StatusMonitor.h.

Referenced by pcl::RealTimeProgressStatus::InfoUpdated(), and pcl::RealTimeProgressStatus::Initialized().

◆ Initialize()

void pcl::StatusMonitor::Initialize	(	const String &	info,
		size_type	count = `0`
	)

Initializes this status monitor to start a new monitoring procedure.

Parameters

info	Progress information.
count	Total progress count. If a zero total progress count is specified, this monitor will be unbounded. That means that the monitor will never reach a completed state by increasing or incrementing it. To complete an unbounded status monitor, the Complete() member function must be called explicitly.

If this monitor has an associated status callback object, this function will call the StatusCallback::Initialized() virtual member function of the associated callback object.

If this function is invoked while an ongoing monitoring procedure is active, it is interrupted and a new monitoring procedure is initialized.

◆ IsAborted()

bool pcl::StatusMonitor::IsAborted ( ) const

inline

Returns true iff a monitoring procedure has been aborted.

When a monitoring procedure is aborted, the status monitor object throws a ProcessAborted exception.

A monitoring procedure can only be aborted by its associated status callback object. This is done by returning a nonzero value from the StatusCallback::Initialized(), StatusCallback::Updated(), or StatusCallback::Completed() virtual member functions implemented by a StatusCallback descendant class.

Definition at line 402 of file StatusMonitor.h.

◆ IsCompleted()

bool pcl::StatusMonitor::IsCompleted ( ) const

inline

Returns true iff this status monitor has completed a monitoring procedure.

A monitoring procedure is completed if the current monitoring counter reaches the total count, or if the Complete() member function is called.

Definition at line 385 of file StatusMonitor.h.

◆ IsInitializationEnabled()

bool pcl::StatusMonitor::IsInitializationEnabled ( ) const

inline

Returns true iff monitor initialization has been disabled for this status monitor object.

See DisableInitialization() for further information on the initialization enabled/disabled states and a source code example.

Definition at line 363 of file StatusMonitor.h.

◆ IsInitialized()

bool pcl::StatusMonitor::IsInitialized ( ) const

inline

Returns true iff this status monitor has been initialized.

A status monitor is initialized by a call to its Initialize() member function.

Definition at line 374 of file StatusMonitor.h.

◆ operator++()

void pcl::StatusMonitor::operator++ ( )

inline

Increments the progress counter of this status monitor.

If the progress counter reaches Total(), and this monitor has an associated status callback object, its StatusCallback::Completed() member function is invoked. If the progress counter is less than Total(), the StatusCallback::Updated() member function will be invoked by the monitoring thread asynchronously.

Note that for unbounded monitors the completed state is never reached unless a explicit call to Complete() is made, hence the StatusCallback::Completed() member function of the status callback object, if any, will never be called by this increment operator.

Definition at line 434 of file StatusMonitor.h.

◆ operator+=()

void pcl::StatusMonitor::operator+= ( size_type n )

inline

Increments the progress counter of this status monitor by the specified number n of progress steps.

This function behaves essentially like the operator ++() function.

Definition at line 446 of file StatusMonitor.h.

◆ operator=()

StatusMonitor& pcl::StatusMonitor::operator= ( const StatusMonitor & x )

inline

Copy assignment operator. Returns a reference to this object.

Definition at line 250 of file StatusMonitor.h.

◆ RefreshRate()

static unsigned pcl::StatusMonitor::RefreshRate ( )

inlinestatic

Returns the progress monitoring refresh rate in milliseconds.

The StatusCallback::Updated() member functions of all active status callback objects are called asynchronously by a low-priority thread. The refresh rate is the interval between successive callback update calls. It can be in the range from 25 to 999 milliseconds.

Definition at line 569 of file StatusMonitor.h.

Referenced by pcl::AbstractImage::RunThreads().

◆ ReturnValue()

int pcl::StatusMonitor::ReturnValue ( ) const

inline

Returns the last status callback return value.

The returned value is the return value of the last call to StatusCallback::Initialized(), StatusCallback::Updated() or StatusCallback::Completed() for the associated status callback object, or zero if no status callback object has been associated with this monitor.

If a nonzero value is returned, then the current monitoring procedure has already been aborted.

Definition at line 516 of file StatusMonitor.h.

◆ SetCallback()

void pcl::StatusMonitor::SetCallback ( StatusCallback * callback )

inline

Associates a status callback object with this status monitor.

Calling this function forces a call to Clear(), which interrupts the current monitoring procedure, if any, and reinitializes the internal state of this monitor.

To associate no status callback object with this monitor, pass nullptr as the argument to this function.

Definition at line 499 of file StatusMonitor.h.

◆ SetInfo()

void pcl::StatusMonitor::SetInfo ( const String & s )

inline

Changes the progress information text for this status monitor.

If there is a status callback object associated with this monitor, its StatusCallback::InfoUpdated() member function is invoked.

Definition at line 413 of file StatusMonitor.h.

◆ SetRefreshRate()

static void pcl::StatusMonitor::SetRefreshRate ( unsigned ms )

static

Sets a new progress monitoring refresh rate in milliseconds.

Parameters

ms	New monitoring refresh rate in milliseconds. The specified value must be between 25 and 999 milliseconds. If the passed value is outside that range, it is discarded and the nearest valid bound is set.

The default refresh rate is 250 milliseconds, or 4 monitoring events per second. The new refresh rate does take effect immediately, even if there are active status monitors.

Note: This function can only be called from the main thread (aka GUI thread). Calling it from a running thread has no effect.

◆ Total()

size_type pcl::StatusMonitor::Total ( ) const

inline

Returns the total progress count for the current monitoring procedure.

When the progress counter reaches the total count, the monitoring procedure has been completed.

Definition at line 547 of file StatusMonitor.h.

Referenced by pcl::RealTimeProgressStatus::Initialized().

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

StatusMonitor.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ StatusMonitor() [1/2]

◆ StatusMonitor() [2/2]

◆ ~StatusMonitor()

Member Function Documentation

◆ Callback() [1/2]

◆ Callback() [2/2]

◆ Clear()

◆ Complete()

◆ Count()

◆ DisableInitialization()

◆ EnableInitialization()

◆ Info()

◆ Initialize()

◆ IsAborted()

◆ IsCompleted()

◆ IsInitializationEnabled()

◆ IsInitialized()

◆ operator++()

◆ operator+=()

◆ operator=()

◆ RefreshRate()

◆ ReturnValue()

◆ SetCallback()

◆ SetInfo()

◆ SetRefreshRate()

◆ Total()