progress bar

Progress Bar (Developer Guide)

Summary

This is a guide to show you some ways to use the new progress bar, which had replaced the old SG_PROGRESS(). The progress bar is composed of a single header file, which can be easily included wherever it is needed. Here I won't discuss the implementation details, but I will rather show you some usage examples which can be useful to apply it to Shogun's algorithm.

Here I will show the method definition, which shows all the available parameters which can be specified. Most of them have already a prefixed value, but they are highly customizable to match the user's needs.

template <typename T>
inline PRange<T> progress(
    Range<T> range, const SGIO& io, std::string prefix = "PROGRESS: ",
    SG_PRG_MODE mode = UTF8,
    std::function<bool()> condition = []() { return true; })
{
	return PRange<T>(range, io, prefix, mode, condition);
}

Here a brief explanation of the various parameters:

• range: the progress bar object takes a range() object to work. This range object is generated by using another custom Shogun's header only library (src/shogun/base/range.h). This gives the lower and upper limits of the loop. Therefore, the progress bar can be used only when the loop has unary steps;
• io: the input/output manager that will be used to print the progress bar on the screen. There is also a progress constructor which does not require to specify the io parameter. The global one will be used instead;
• prefix: a string which represents a title which will be prefixed to the progress bar. It can be used to specify what the progress bar is for;
• mode: this parameter selects if we want the progress bar to be printed with UTF-8 or ASCII chars;
• condition: this is a lambda parameter which can be used to specify a premature stopping condition of the loops (it is better to use it when using the progress a range-based for loop);

Examples

Basic usage

This is an example of the basic usage of a progress object. The method print_progress() has to be called whenever we want to update the progress bar. The method complete() terminate the progress bar printing and must be called once, at the end of the loop. This version can be also used under multi-threaded environment. However, be advised that the execution might slow down a bit since we use locks to synchronize the threads to print a good looking progress bar.

// Create a progress bar object
auto pb = progress(range(0,10));

// Main Loop
for (int i=0; i<10; i++)
{
    // Magic stuff
    pb.print_progress();
}
pb.complete();

Range-based loops

If the loop is plain and simple, this cool C++11 version can be used. The main differences from the basic version are that there is no need to call manually print_progress() or complete() methods, since the progress object will do that automagically.

// It can be used also with the new range-based for loop
// introduced with C++11 standard.
for (auto i: progress(range(0, 10)))
{
    // Revolutionary code
}

Advanced usage

This is an example of a more complex usage. Since progress support also custom stopping condition, here we are using a lambda to specify that the loop must end when the variable condition will have a value greater or equal to 5. Lambdas passed as condition must evaluate true, when the loop can continue, and false when the loop needs to end.

int condition=1;
for (auto i : progress(
    range(0, 10),
    "PROGRESS: ",
    UTF8,
    [&]{ return condition < 5;})
)
{
     condition++;
     // This will stop when condition >= 5;
}