Geogram  Version 1.9.1-rc
A programming library of geometric algorithms
GEO::ProgressTask Class Reference

Tracks the progress of a task. More...

#include <geogram/basic/progress.h>

Public Member Functions

 ProgressTask (const std::string &task_name, index_t max_steps, bool quiet)
 Creates a logger for a task. More...
 
 ProgressTask (const std::string &task_name="", index_t max_steps=100)
 Creates a logger for a task. More...
 
virtual ~ProgressTask ()
 Destroys a ProgressTask. More...
 
virtual void progress (index_t step)
 Sets the current execution step. More...
 
virtual void next ()
 Goes to the next step. More...
 
bool is_canceled () const
 Checks if the task is canceled. More...
 
void reset ()
 Resets the execution step. More...
 
void reset (index_t max_steps)
 Resets the execution step. More...
 
const std::string & task_name () const
 Gets the name of the task.
 
double start_time () const
 Gets the start time of the task.
 
index_t max_steps () const
 Gets the number of steps of the task.
 
index_t step () const
 Gets the current step of the task.
 
index_t percent () const
 Gets the percentage of completion of the task.
 

Protected Member Functions

virtual void update ()
 Updates progress values. More...
 

Detailed Description

Tracks the progress of a task.

The progress of a task can be represented by a number of steps to execute. As the task progresses, the client code informs the ProgressTask of the execution step by calling function next() or progress(), which notify the LoggerClients of the progress. Finally, when the current logger goes out of scope (is destroyed), the logger notifies the LoggerClients that the task is terminated.

When a task is canceled by Progress::cancel() the next call to progress() throws an exception TaskCanceled. It is the responsibility of the client code to catch this exception and do appropriate cleanup. The recommended usage of ProgressTask is illustrated below:

try {
ProgressTask task("something to do", 100);
for(size_t i = 0; i < 100; ++i) {
do_something();
task.progress(i);
}
}
catch(const TaskCanceled&) {
// Do early cleanup
}
ProgressTask(const std::string &task_name, index_t max_steps, bool quiet)
Creates a logger for a task.

ProgressTask can be sub-classed by client code, typically to route progress display to a progress bar.

Definition at line 240 of file progress.h.

Constructor & Destructor Documentation

◆ ProgressTask() [1/2]

GEO::ProgressTask::ProgressTask ( const std::string &  task_name,
index_t  max_steps,
bool  quiet 
)

Creates a logger for a task.

This creates a ProgressTask object for task task_name with a number of steps given by max_steps. The registered LoggerClient is notified to start listening to the progress of the task.

Parameters
[in]task_namethe name of the task
[in]max_stepsthe number of steps of the task
[in]quietset to true to make the progress silent
See also
LoggerClient::begin()

◆ ProgressTask() [2/2]

GEO::ProgressTask::ProgressTask ( const std::string &  task_name = "",
index_t  max_steps = 100 
)

Creates a logger for a task.

This creates a ProgressTask object for task task_name with a number of steps given by max_steps. The registered LoggerClient is notified to start listening to the progress of the task.

Parameters
[in]task_namethe name of the task
[in]max_stepsthe number of steps of the task

◆ ~ProgressTask()

virtual GEO::ProgressTask::~ProgressTask ( )
virtual

Destroys a ProgressTask.

This notifies the registered LoggerClients that the task is terminated.

See also
LoggerClient::end()

Member Function Documentation

◆ is_canceled()

bool GEO::ProgressTask::is_canceled ( ) const

Checks if the task is canceled.

This function must be called as often as possible during the execution of the current task to stop the current task in case a request was made to cancel it (e.g., from the user interface).

Return values
trueif the task was canceled
falseotherwise

◆ next()

virtual void GEO::ProgressTask::next ( )
virtual

Goes to the next step.

This increments the current step value by 1. This updates the percentage of completion of the task and notifies the registered LoggerClients that the execution step has changed.

See also
update()

◆ progress()

virtual void GEO::ProgressTask::progress ( index_t  step)
virtual

Sets the current execution step.

This sets the current step value to step. The new value must not be greater than the configured number of steps in the ProgressTask constructor. This updates the percentage of completion of the task and notifies the registered LoggerClients that the execution step has changed.

Parameters
[in]stepthe new step value
See also
update()
Exceptions
TaskCanceled

◆ reset() [1/2]

void GEO::ProgressTask::reset ( )

Resets the execution step.

Resets progress at the beginning. This updates the percentage of completion of the task and notifies the registered LoggerClients that the execution step has changed. This is equivalent to call progress(0).

See also
progress()

◆ reset() [2/2]

void GEO::ProgressTask::reset ( index_t  max_steps)

Resets the execution step.

This changes the maximum number of steps to max_steps and resets progress at the beginning. This updates the percentage of completion of the task and notifies the registered LoggerClients that the execution step has changed.

Parameters
[in]max_stepsthe new number of steps of the task.
See also
LoggerClient::progress()

◆ update()

virtual void GEO::ProgressTask::update ( )
protectedvirtual

Updates progress values.

Updates the percentage of completion of the task and notifies the registered LoggerClients that the execution step has changed.

See also
LoggerClient::progress()

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