kjb::Heartbeat Class Reference

A class for for indicating the status of slow-moving loops. More...

#include <l_heartbeat.h>

Public Member Functions
	Heartbeat (const std::string &message, unsigned total=1, unsigned masklen=10)
	Make a "heart" which will beat while your slow algorithm runs. More...
std::string	beat ()
	Indicate one tiny step of your algorithm's execution. More...
std::string	stop () const
	Call this when your algorithm is finished, to see total time. More...

Detailed Description

A class for for indicating the status of slow-moving loops.

This class is really only appropriate when you know in advance how many iterations will occur for your loop. Assuming you know that number, then you would use this class something like as shown

Heartbeat heart( "Eating green eggs and ham", BAZILLION ); // ctor
for( int iteration = 0; iteration < BAZILLION; ++iteration )
{
     heart.beat();   // call at every single iteration
     Grn_eggs_ham.eat( iteration );
}
heart.stop(); // call stop() one time, at the end of the code

Todo:

: show some sample output here

Constructor & Destructor Documentation

kjb::Heartbeat::Heartbeat	(	const std::string &	message,
		unsigned	total = 1,
		unsigned	masklen = 10
	)

Make a "heart" which will beat while your slow algorithm runs.

Parameters

message	Name or short description of the algorithm
total	Total number of beats, that is, the number of steps the algorithm will run.
masklen	Indicates the period of the heartbeat, i.e., a big value means (exponentially) slower beat. Fraction of calls to beat() that produce output is two raised to minus this power (hence default is that out of 1024 calls to beat(), only one produces output).

The idea is that you call the beat() method for this object inside the outermost loop of your code, and a fraction, such as one in every 1024 calls to beat(), causes timing output to be emitted on standard output.

This ctor calls isatty(3) to determine if it can recycle the line it is printing to; if standard input is a TTY (not a file) then this uses the carriage return character to re-use the line. But if it is a file, then this emits a newline character and each output string thus shows up on a separate line. A kluge.

Member Function Documentation

std::string kjb::Heartbeat::beat ( )

inline

Indicate one tiny step of your algorithm's execution.

This indicates one small step of your algorithm or loop is occurring, which usually passes silently, but on a deliberately small fraction of calls to this method, some timing output will be generated and sent to console standard error so that the user of the program does not despair.

However, that's only if standard input is attached TO the console, i.e., you are running the program "interactively." If standard input is not coming from a TTY, then this object assumes the program is running in batch mode, in which case this method emits nothing to standard output.

Also the same string is returned, in case you want it. (For maximum speed, just ignore the string that is returned.)

Returns

the progress string that was emitted via stdout.

std::string kjb::Heartbeat::stop ( ) const

inline

Call this when your algorithm is finished, to see total time.

This is an optional cleanup method; if you call it (ONCE) at the end of your algorithm or loop, then you can show the user the total amount of time expended during the loop.

This method sends its output to standard output regardless of whether it thinks the program is interactive.

Returns

output string that was sent to stdout, in case you want a copy

---

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

• /work/kobus/src/lib/l_cpp/l_heartbeat.h
• /work/kobus/src/lib/l_cpp/l_heartbeat.cpp