PCL
pcl::StatusMonitor Class Reference

An asynchronous status monitoring system. More...

#include <StatusMonitor.h>

Public Member Functions

 StatusMonitor ()=default
 
 StatusMonitor (const StatusMonitor &x)
 
virtual ~StatusMonitor ()
 
const StatusCallbackCallback () const
 
StatusCallbackCallback ()
 
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)
 
StatusMonitoroperator= (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

Constructs a StatusMonitor object as a duplicate of an existing instance.

Definition at line 235 of file StatusMonitor.h.

◆ ~StatusMonitor()

virtual pcl::StatusMonitor::~StatusMonitor ( )
inlinevirtual

Destroys this StatusMonitor object.

Definition at line 243 of file StatusMonitor.h.

Member Function Documentation

◆ Callback() [1/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 475 of file StatusMonitor.h.

◆ Callback() [2/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 485 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 557 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 464 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 537 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 338 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 352 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 526 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
infoProgress information.
countTotal 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 403 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 386 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 364 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 375 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 435 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 447 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 251 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 570 of file StatusMonitor.h.

◆ 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 517 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 500 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 414 of file StatusMonitor.h.

◆ SetRefreshRate()

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

Sets a new progress monitoring refresh rate in milliseconds.

Parameters
msNew 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.

◆ 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 548 of file StatusMonitor.h.

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


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