progress.c File Reference

The main progress bar library definition file. More...

#include <stdio.h>
#include <string.h>
#include <stdarg.h>
#include <sys/types.h>
#include <talloc.h>
#include <math.h>
#include <errno.h>
#include <stdlib.h>
#include "pwlib.h"
#include "progress.h"

Data Structures

struct  ProgressInfo_struct
 The actual structure of the Progressor object we pass around. More...

Defines

#define PROGRESS_TIME_WIDTH   10

Functions

static void _P_debug (PInfo *p, const char *fmt,...) __attribute__((format(printf
 Print debugging information to the debug log.
static void _P_open_debug_log (PInfo *p)
 Open the debug log file and start outputting to it.
PInfoP_new (long min, long max)
 Create a new PInfo object.
void P_set_debugging (PInfo *p)
 Activate debug logging on the fly.
void P_clear_debugging (PInfo *p)
 Deactivate debug logging on the fly.
void P_set_limits (PInfo *p, long min, long max)
 Set a new minimum and maximum for an existing bar.
void P_set_sub_limits (PInfo *p, long submin, long submax)
 Set the sub bar's limits for the given bar.
void P_set_width (PInfo *p, unsigned int width)
 Sets the width in characters of an existing bar.
void P_set_bar (PInfo *p, char left, char right, char empty, char fill)
 Set the characters used to display the bar chart.
void P_set_subchar (PInfo *p, char subchar)
 Set the sub-bar progress character.
void P_set_title (PInfo *p, char *title)
 Sets the bar's title.
void P_clear_title (PInfo *p)
 Clears any title previously set.
void P_set_interval (PInfo *p, double interval)
 Set the interval between the bar being displayed.
void P_freeze (PInfo *p)
 Freeze progress.
void P_thaw (PInfo *p)
 Resume progress.
long P_start (PInfo *p)
 Reset the bar to start now.
void P_inc (PInfo *p)
 Increment the bar's current position.
void P_subinc (PInfo *p)
 Increment the sub-bar's current position.
void P_set (PInfo *p, long cur)
 Sets the progress bar's value directly.
void P_subset (PInfo *p, long subcur)
 Sets the sub-bar's value directly.
void P_reset (PInfo *p)
 Reset the bar's current value.
void P_subreset (PInfo *p)
 Reset the sub-bar's current value.
void P_finish (PInfo *p)
 Move the bar's current value to the maximum value.
void P_subfinish (PInfo *p)
 Finish the progress of the sub-bar.
double P_ratio (PInfo *p)
 Returns the ratio of completion (between 0 and 1).
double P_subratio (PInfo *p)
 Returns the ratio of the sub-bar completion.
long P_next_val (PInfo *p)
 Calculates the next value at which print should be called.
long P_next_sub_val (PInfo *p)
 Calculates the next sub-bar value at which print should be called.
long P_print (PInfo *p)
 Print the progress bar.
void P_erase (PInfo *p)
 Erase the bar from the display.
double P_elapsed (PInfo *p)
 Return the amount of elapsed time spent in processing so far.
double P_persec (PInfo *p)
 Return the number of values progressed through per second.
double P_remain (PInfo *p)
 Calculate the remaining number of seconds in processing.
void P_destroy (PInfo *p)
 Destroy the given PInfo object.

Variables

void * progress_context = NULL
 the talloc context for object memory allocations


Detailed Description

The main progress bar library definition file.


Define Documentation

#define PROGRESS_TIME_WIDTH   10


Function Documentation

static void static void _P_debug ( PInfo p,
const char *  fmt,
  ... 
) [static]

Print debugging information to the debug log.

Writes debugging information to the debug log. No information is included in the log other than what you give it.

Parameters:
p Progress bar object.
[in] fmt The printf-like format to write.
... Any other variables required for the format string.

static void _P_open_debug_log ( PInfo p  )  [static]

Open the debug log file and start outputting to it.

This generates a new debugging file name and tries to open it.

void P_clear_debugging ( PInfo p  ) 

Deactivate debug logging on the fly.

This allows the caller to turn debugging on a progress bar off while the bar is in use.

Parameters:
p Progress bar object.
See also:
P_new

P_set_debugging

void P_clear_title ( PInfo p  ) 

Clears any title previously set.

The given bar object no longer displays a title, and any title that had been allocated to it is discarded.

Parameters:
p Progress bar object.

void P_destroy ( PInfo p  ) 

Destroy the given PInfo object.

This is the destructor function of the PInfo 'object'. It closes any debugging file that had been opened and frees all memory allocated to the object. The object should not be used thereafter and this function attempts to make it so.

Parameters:
p Progress bar object.
See also:
P_new

double P_elapsed ( PInfo p  ) 

Return the amount of elapsed time spent in processing so far.

The duration in seconds between when the bar was created or started, and now, is returned. If the bar has been frozen, any time elapsed since the freeze time is ignored.

Parameters:
p Progress bar object.
Returns:
Number of seconds elapsed since the bar was created.
See also:
P_new

P_start

P_freeze

P_thaw

void P_erase ( PInfo p  ) 

Erase the bar from the display.

This function prints enough space to completely erase the bar from your display.

Parameters:
p Progress bar object.
See also:
P_print

void P_finish ( PInfo p  ) 

Move the bar's current value to the maximum value.

This function is used to indicate that the work has been completed. If you're breaking out of a loop early because the work has been completed, then this allows that final printing of the progress bar to display completion.

Parameters:
p Progress bar object.
See also:
P_start

P_reset

P_set_limits

P_print

void P_freeze ( PInfo p  ) 

Freeze progress.

This 'freezes' all progress on the bar. No time is deemed to elapse for the bar after this is called. This makes it useful for stopping the state of a bar after completion of the actual task but before calculations of its intervals per second and so forth. This has no effect if the bar is already frozen.

Parameters:
p Progress bar object.
See also:
P_thaw

P_start

void P_inc ( PInfo p  ) 

Increment the bar's current position.

Calling this increments the bar's current value. It may go beyond the set maximum. This is usually called once per iteration; it saves setting the value of the bar explicitly.

Parameters:
p Progress bar object.
See also:
P_set

P_start

P_set_limits

PInfo* P_new ( long  min,
long  max 
)

Create a new PInfo object.

Creates a new PInfo object that goes from min to max, and sets it up with the default bar configuration:

long P_next_sub_val ( PInfo p  ) 

Calculates the next sub-bar value at which print should be called.

Basically similar to P_next_val(), but here we're only reporting the next sub-bar value at which P_print() should be called in order to print on the time interval. If this should be longer than it takes to complete the sub-task and even move further on in the overall task, it is irrelevant. In those cases, the maximum sub-bar value will be returned. It also makes no attempt to determine how big this sub-task is in relation to other sub-tasks, or the overall task. It's only concerned with this particular 'instance' of the sub-bar.

Parameters:
p Progress bar object.
Returns:
The next value at which the bar will be ready to print.

long P_next_val ( PInfo p  ) 

Calculates the next value at which print should be called.

This value is an estimate of the iteration in the loop at which the elapsed time between prints will be passed. The canonical method of minimising calls to P_print (which will return without printing if it's too early to be printed anyway) is the following code:

    int next, bytes = 0;
    PInfo *p = P_new(0,file_len);
    next = P_start(p);
    while (!feof(fp)) {
        bytes += fread(buf, BUF_SIZE, 1, fp);
        do_lots_of_processing(buf);
        if (next < bytes) {
            P_set(p, bytes);
            next = P_print(p);
        }
    }

Parameters:
p Progress bar object.
Returns:
The next value at which the bar will be ready to print.

double P_persec ( PInfo p  ) 

Return the number of values progressed through per second.

This function uses the elapsed time (qv P_elapsed()) and the current value, in relation to the minimum and maximum values, to give a calculation of how many 'values' (e.g. iterations) have been performed per second so far. If the bar has a sub-bar, the progress of this sub-bar through its own value range is taken into account in calculating the bar's position.

Parameters:
p Progress bar object.
Returns:
The number of iterations per second done so far.

long P_print ( PInfo p  ) 

Print the progress bar.

Ah, the moment you've been waiting for. This function checks that more time than the print interval has passed; if not, it returns early. If not, it prints whatever components are currently enabled of the bar: the "cur of max" display, the title, the bar with its attendant sub-bar position if required, and the estimated time to completion. The ETC information is using a routine from the pwlib library to print the remaining duration in a short, fixed-length format - basically you get about four significant digits of time precision.

The bar is hard-limited to be between 0 and 100 percent full; while the progress meter itself can be outside these values, the bar will try to maintain a sane display.

The bar prints a carriage return (\r, ctrl-M) before any display in order to overwrite itself. Therefore, printing anything else to standard output while using a bar is discouraged and will cause the bar to appear once per line. Setting the bar's screen width to be too large for the current screen will also give this result.

The function returns the next value at which you should attempt to print the bar given the current estimates of how fast the process is working through the value range and the print interval. It uses P_next_val() or P_next_sub_val() as appropriate (qv). In other words, if the bar currently has sub-bar information, the next sub-bar value is returned, otherwise the next main bar value is returned.

Parameters:
p Progress bar object.
See also:
P_set

P_next_val

P_next_sub_val

Returns:
The next value at which to print.

double P_ratio ( PInfo p  ) 

Returns the ratio of completion (between 0 and 1).

This function calculates the ratio $(cur - min) / (max - min)$. The completion ratio of the sub-bar is taken into account - it's added as a fractional component to the current value. This will return values outside the range between 0 and 1 if the current value is correspondingly outside its minimum and maximum values.

Parameters:
p Progress bar object.
Returns:
The completion ratio between 0 and 1.

double P_remain ( PInfo p  ) 

Calculate the remaining number of seconds in processing.

As opposed to the elapsed time in processing (qv P_elapsed()), this function uses the number of iterations per second (qv P_persec()) to calculate the estimated time left in processing, if processing continues at its current rate. This is, of course, highly variable in early stages and can still change significantly depending on processor load, data, and other external factors.

Parameters:
p Progress bar object.
Returns:
The number of seconds remaining in processing.

void P_reset ( PInfo p  ) 

Reset the bar's current value.

Resets the current value to the minimum. If you have to restart the loop for some reason, this would be what you use. It does not reset the starting time - in other words, it assumes that you now have to do the work done to get thus far _and_ the rest of the iterations in order to complete the task.

Parameters:
p Progress bar object.
See also:
P_start

void P_set ( PInfo p,
long  cur 
)

Sets the progress bar's value directly.

This sets the position of the bar directly. Use this if you are moving in increments greater than one. For instance, if you are reading a file, and the file's size is the maximum, then you keep a tally of the number of bytes read so far and set the bar's position after each read.

Parameters:
p Progress bar object.
cur The current position of the bar.
See also:
P_set_limits

void P_set_bar ( PInfo p,
char  left,
char  right,
char  empty,
char  fill 
)

Set the characters used to display the bar chart.

Sets the characters used to set the left and right edges of the bar chart and the characters that make up the empty and full space within the bar.

Parameters:
p Progress bar object.
left The character to use at the left of the bar.
right The character to use at the right of the bar.
empty The character to fill empty (uncompleted) space with.
fill The chracter to fill competed space with.

void P_set_debugging ( PInfo p  ) 

Activate debug logging on the fly.

This allows the caller to turn debugging on a progress bar on while the bar is in use.

Parameters:
p Progress bar object.
See also:
P_new

P_clear_debugging

void P_set_interval ( PInfo p,
double  interval 
)

Set the interval between the bar being displayed.

This sets the interval that the progress bar uses to determine at what iteration to next display the bar. See the working example on bar display for how this is controlled.

Parameters:
p Progress bar object.
interval The number of seconds between displays - can be fractional.

void P_set_limits ( PInfo p,
long  min,
long  max 
)

Set a new minimum and maximum for an existing bar.

Sets a new minimum and maximum for the given bar, and resets the position in the bar to the minimum value. If the minimum value is greater than the maximum, they are swapped before the bar is updated.

Parameters:
p Progress bar object.
[in] min The new minimum value.
[in] max The new maximum value.
See also:
P_new

P_start

P_finish

P_reset

void P_set_sub_limits ( PInfo p,
long  submin,
long  submax 
)

Set the sub bar's limits for the given bar.

This function starts a new sub-bar in the given bar, with the given minimum and maximum values. If the bar had sub-bar information set already, this is set to the new parameters. The sub-bar value is set to the given minimum value. If the minimum is greater than the maximum, they are swapped before the bar is updated.

Parameters:
p Progress bar object.
[in] submin New minimum sub-bar value
[in] submax New maximum sub-bar value
See also:
P_subreset

void P_set_subchar ( PInfo p,
char  subchar 
)

Set the sub-bar progress character.

The sub-bar progress is only given as a single character within the bar. This function allows you to set that character.

Parameters:
p Progress bar object.
subchar The character to put at the progress location of the sub-bar.

void P_set_title ( PInfo p,
char *  title 
)

Sets the bar's title.

Takes the given string as the new current title of the bar. This string is copied rather than use the original pointer, so you can free the string after it's been sent here if you want. This may change in the future. If a title has been previously allocated, it is overwritten. The title will be shown to the left of the bar chart.

Parameters:
p Progress bar object.
title The new string to put in the bar's title.
Returns:
???
Todo:
Maybe this should just take a pointer to the original string rather than strdup'ing it?

void P_set_width ( PInfo p,
unsigned int  width 
)

Sets the width in characters of an existing bar.

Sets the total width of the bar including all the currently displayed elements.

Parameters:
p Progress bar object.
[in] width New width in characters.

long P_start ( PInfo p  ) 

Reset the bar to start now.

This starts progress again at the previously set minimum value, optionally thawing the object if it's frozen. Starting the bar is not necessary if it has just been created with P_new. As a side effect, it returns the next value to be iterated through; this is used for setting the next iteration to print.

Parameters:
p Progress bar object.
Returns:
The next value at which to attempt printing.
See also:
P_freeze

P_thaw

P_new

P_next_val

void P_subfinish ( PInfo p  ) 

Finish the progress of the sub-bar.

See the P_finish function - this just does the same to the sub-bar.

Parameters:
p Progress bar object.
See also:
P_set_sub_limits

P_subreset

void P_subinc ( PInfo p  ) 

Increment the sub-bar's current position.

This does for the sub-bar what P_inc does for the main bar.

Parameters:
p Progress bar object.
See also:
P_inc

P_set_sub_limits

double P_subratio ( PInfo p  ) 

Returns the ratio of the sub-bar completion.

This function calculates the ratio $(cur - min) / (max - min)$ for the sub-bar alone. The P_ratio function also uses this in its ratio calculation.

Parameters:
p Progress bar object.
Returns:
The sub-bar completion ratio between 0 and 1.
See also:
P_ratio

void P_subreset ( PInfo p  ) 

Reset the sub-bar's current value.

This does the same thing for the sub-bar that P_reset does for the main bar.

Parameters:
p Progress bar object.
See also:
P_substart

void P_subset ( PInfo p,
long  subcur 
)

Sets the sub-bar's value directly.

As P_set sets the main bar's progress, so P_subset sets the sub-bar's progress.

Parameters:
p Progress bar object.
subcur The current position of the sub-bar.
See also:
P_set

P_set_sub_limits

void P_thaw ( PInfo p  ) 

Resume progress.

If the bar is currently frozen, the state is 'thawed'. Any time elapsed between the call to freeze the bar and now is added to the start time, thus moving the start time 'later' and thus cancelling out the time spent 'frozen'. If the bar is not frozen, this has no effect.

Parameters:
p Progress bar object.
See also:
P_freeze

P_start


Variable Documentation

void* progress_context = NULL

the talloc context for object memory allocations


Generated on Fri Jan 23 11:58:35 2009 for Progress by  doxygen 1.4.7