BStopWatch

Derived from: none

Declared in: be/support/StopWatch.h

Library: libbe.so

Summary

The BStopWatch class is a debugging tool designed to time the execution of portions of your code. When a BStopWatch object is constructed, it starts an internal timer. When it's deleted, it stops the timer and prints the elapsed time to standard out in this format:

StopWatch "name": f usecs.

Where name is the name that you gave to the object when you constructed it, and f is the elapsed time in microseconds.

Look at all these other things you can do...

• Suspend, resume, and reset the timer (Suspend(), Resume(), Reset()).

• Ask for the current elapsed time without stopping the timer (ElapsedTime()).

• Record "lap points" that are printed out at the end of the run (Lap()).

Using a BStopWatch is simple; this...

   BStopWatch *watch = new BStopWatch("Timer 0");
   /* The code you want to time goes here. */
   delete watch;
   ...

...will produce, on standard out, a message that goes something like this:

   StopWatch "Timer 0": 492416 usecs.

This would indicate that the timed code took about half a second to execute—remember, you're looking at microseconds.

If you want to time an entire function, just toss a StopWatch on the stack:

   void MyFunc()
   {
      BStopWatch watch("Timer 0");
      ...
   }

When the function returns, the BStopWatch prints its message.

BStopWatch objects are useful if you want to get an idea of where your cycles are going. But you shouldn't rely on them for painfully accurate measurements.

Constructor and Destructor

BStopWatch()

	BStopWatch(const char *name, bool silent = false)

Creates a BStopWatch object, names it, and starts its timer. If silent is false (the default), the object will print its elapsed time when it's destroyed; otherwise the message isn't printed. To get the elapsed time from a silent BStopWatch, call ElapsedTime().

~BStopWatch()

	~BStopWatch()

Stops the object's timer, prints a timing message to standard out (unless it's running silently), and then destroys the object. By default the timing message looks like this:

StopWatch "name": f usecs.

If you've recorded some lap points (through the Lap() function), you'll also see the lap times as well:

StopWatch "name": f usecs. [lap#: soFar#thisLap] [lap#: soFar#thisLap] [lap#: soFar#thisLap]...

...where lap# is the number of the lap, soFar was the total elapsed time at that lap, and thisLap was the time it took to complete the lap.

Member Functions

ElapsedTime()

	bigtime_t ElapsedTime(void) const

Returns the elapsed time, in microseconds, since the object was created or last Reset(). This function doesn't print the time message, nor does it touch the timer (the timer keeps running—unless it's paused).

   BStopWatch watch("Timer 0");
   ...
   printf("Elapsed time:  %Ldn", watch.ElapsedTime());

Lap()

	bigtime_t Lap()

Records a "lap point" and returns the total elapsed time so far. The lap point times are printed individually when the object is destroyed, provided the object isn't silent. You can record as many as eight lap points; if you ask for a ninth lap point, the lap isn't recorded and this function returns 0. See ~BStopWatch() for a description of what the lap points look like when they're printed.

Name()

	const char *Name(void) const

Returns the name of the object, as set in the constructor.

Reset() see Suspend()

Resume() see Suspend()

Suspend() , Resume() , Reset()

	void Suspend(void) void Resume(void) void Reset(void)

These functions affect the object's timer.

Suspend() stops the timer but doesn't reset it.

Resume() starts the timer running again.

Reset() sets the elapsed time to 0, but doesn't stop the timer. You can call Reset() at any time, regardless of whether the object is running or suspended.