Developer documentation
Version 3.0.3-105-gd3941f44
MR::ProgressBar Class Reference

implements a progress meter to provide feedback to the user More...

#include "progressbar.h"

Classes

struct  SwitchToMultiThreaded
 

Public Member Functions

 ProgressBar ()
 Create an unusable ProgressBar. More...
 
 ProgressBar (const ProgressBar &p)=delete
 
 ProgressBar (ProgressBar &&p)=default
 
 ~ProgressBar ()
 
 ProgressBar (const std::string &text, size_t target=0, int log_level=1)
 Create a new ProgressBar, displaying the specified text. More...
 
 operator bool () const
 returns whether the progress will be shown More...
 
bool operator! () const
 returns whether the progress will be shown More...
 
size_t value () const
 
size_t count () const
 
bool show_percent () const
 
bool text_has_been_modified () const
 
const std::string & text () const
 
const std::string & ellipsis () const
 
void set_max (size_t new_target)
 set the maximum target value of the ProgressBar More...
 
void set_text (const std::string &new_text)
 
template<class TextFunc >
void update (TextFunc &&text_func, bool increment=true)
 update text displayed and optionally increment counter More...
 
void operator++ ()
 increment the current value by one. More...
 
void operator++ (int)
 
void done ()
 
template<class ThreadType >
void run_update_thread (const ThreadType &threads) const
 

Static Public Member Functions

static bool set_update_method ()
 

Public Attributes

bool first_time
 
size_t last_value
 

Static Public Attributes

static void(* display_func )(const ProgressBar &p)
 
static void(* done_func )(const ProgressBar &p)
 
static void(* previous_display_func )(const ProgressBar &p)
 
static std::condition_variable notifier
 
static bool notification_is_genuine
 
static std::mutex mutex
 
static void * data
 

Detailed Description

implements a progress meter to provide feedback to the user

The ProgressBar class displays a text message along with a indication of the progress status. For command-line applications, this will be shown on the terminal. For GUI applications, this will be shown as a graphical progress bar.

It has two modes of operation:

  • percentage completion: if the maximum value is non-zero, then the percentage completed will be displayed. Each call to ProgressBar::operator++() will increment the value by one, and the percentage displayed is computed from the current value with respect to the maximum specified.
  • busy indicator: if the maximum value is set to zero, then a 'busy' indicator will be shown instead. For the command-line version, this consists of a dot moving from side to side.

Other implementations can be created by overriding the display_func() and done_func() static functions. These functions will then be used throughout the application.

Definition at line 58 of file progressbar.h.

Constructor & Destructor Documentation

◆ ProgressBar() [1/4]

MR::ProgressBar::ProgressBar ( )
inline

Create an unusable ProgressBar.

Definition at line 62 of file progressbar.h.

◆ ProgressBar() [2/4]

MR::ProgressBar::ProgressBar ( const ProgressBar p)
delete

◆ ProgressBar() [3/4]

MR::ProgressBar::ProgressBar ( ProgressBar &&  p)
default

◆ ~ProgressBar()

MR::ProgressBar::~ProgressBar ( )
inline

Definition at line 66 of file progressbar.h.

◆ ProgressBar() [4/4]

MR::ProgressBar::ProgressBar ( const std::string &  text,
size_t  target = 0,
int  log_level = 1 
)
inline

Create a new ProgressBar, displaying the specified text.

If target is unspecified or set to zero, the ProgressBar will display a busy indicator, updated at regular time intervals. Otherwise, the ProgressBar will display the percentage completed, computed from the number of times the ProgressBar::operator++() function was called relative to the value specified with target.

Definition at line 192 of file progressbar.h.

Member Function Documentation

◆ count()

size_t MR::ProgressBar::count ( ) const
inline

Definition at line 95 of file progressbar.h.

◆ done()

void MR::ProgressBar::done ( )
inline

Definition at line 138 of file progressbar.h.

◆ ellipsis()

const std::string & MR::ProgressBar::ellipsis ( ) const
inline

Definition at line 99 of file progressbar.h.

◆ operator bool()

MR::ProgressBar::operator bool ( ) const
inline

returns whether the progress will be shown

The progress may not be shown if the -quiet option has been supplied to the application.

Returns
true if the progress will be shown, false otherwise.

Definition at line 82 of file progressbar.h.

◆ operator!()

bool MR::ProgressBar::operator! ( ) const
inline

returns whether the progress will be shown

The progress may not be shown if the -quiet option has been supplied to the application.

Returns
true if the progress will not be shown, false otherwise.

Definition at line 90 of file progressbar.h.

◆ operator++() [1/2]

void MR::ProgressBar::operator++ ( )
inline

increment the current value by one.

Definition at line 283 of file progressbar.h.

◆ operator++() [2/2]

void MR::ProgressBar::operator++ ( int  )
inline

Definition at line 136 of file progressbar.h.

◆ run_update_thread()

template<class ThreadType >
void MR::ProgressBar::run_update_thread ( const ThreadType &  threads) const
inline

Definition at line 310 of file progressbar.h.

◆ set_max()

void MR::ProgressBar::set_max ( size_t  new_target)
inline

set the maximum target value of the ProgressBar

This function should only be called if the ProgressBar has been created with a non-zero target value. In other words, the ProgressBar has been created to display a percentage value, rather than a busy indicator.

Definition at line 213 of file progressbar.h.

◆ set_text()

void MR::ProgressBar::set_text ( const std::string &  new_text)
inline

Definition at line 228 of file progressbar.h.

◆ set_update_method()

static bool MR::ProgressBar::set_update_method ( )
static

◆ show_percent()

bool MR::ProgressBar::show_percent ( ) const
inline

Definition at line 96 of file progressbar.h.

◆ text()

const std::string & MR::ProgressBar::text ( ) const
inline

Definition at line 98 of file progressbar.h.

◆ text_has_been_modified()

bool MR::ProgressBar::text_has_been_modified ( ) const
inline

Definition at line 97 of file progressbar.h.

◆ update()

template<class TextFunc >
void MR::ProgressBar::update ( TextFunc &&  text_func,
bool  increment = true 
)
inline

update text displayed and optionally increment counter

This expects a function, functor or lambda function that should return a std::string to replace the text. This functor will only be called when necessary, i.e. when BUSY_INTERVAL time has elapsed, or if the percentage value to display has changed. The reason for passing a functor rather than the text itself is to minimise the overhead of forming the string in cases where this is sufficiently expensive to impact performance if invoked every iteration. By passing a function, this operation is only performed when strictly necessary.

The simplest way to use this method is using C++11 lambda functions, for example:

progress.update ([&](){ return "current energy = " + str(energy_value); });
std::string str(const T &value, int precision=0)
Definition: mrtrix.h:247
Note
due to this lazy update, the text is not guaranteed to be up to date by the time processing is finished. If this is important, you should also use the set_text() method to set the final text displayed before the ProgressBar's done() function is called (typically in the destructor when it goes out of scope).

Definition at line 250 of file progressbar.h.

◆ value()

size_t MR::ProgressBar::value ( ) const
inline

Definition at line 94 of file progressbar.h.

Member Data Documentation

◆ data

void* MR::ProgressBar::data
static

Definition at line 163 of file progressbar.h.

◆ display_func

void(* MR::ProgressBar::display_func) (const ProgressBar &p)
static

Definition at line 156 of file progressbar.h.

◆ done_func

void(* MR::ProgressBar::done_func) (const ProgressBar &p)
static

Definition at line 157 of file progressbar.h.

◆ first_time

bool MR::ProgressBar::first_time
mutable

Definition at line 165 of file progressbar.h.

◆ last_value

size_t MR::ProgressBar::last_value
mutable

Definition at line 166 of file progressbar.h.

◆ mutex

std::mutex MR::ProgressBar::mutex
static

Definition at line 162 of file progressbar.h.

◆ notification_is_genuine

bool MR::ProgressBar::notification_is_genuine
static

Definition at line 161 of file progressbar.h.

◆ notifier

std::condition_variable MR::ProgressBar::notifier
static

Definition at line 160 of file progressbar.h.

◆ previous_display_func

void(* MR::ProgressBar::previous_display_func) (const ProgressBar &p)
static

Definition at line 158 of file progressbar.h.


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