The Support Kit: BStopWatch

Derived from: (nada)

Declared in: be/support/StopWatch.h

Library: libbe.so

Overview

The BStopWatch class is a debugging tool that you can use to time the execution of portions of your code. When a BStopWatch object is constructed, it starts its 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.

Caveats

		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.
		Unlike the other debugging tools defined by the Support Kit, there's no run-time toggle to control a BStopWatch. Make sure you remove your BStopWatch objects after you're done debugging your code.

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 its destroyed; if it's true, the message isn't printed. To get the elapsed time from a silent BStopWatch, call ElapsedTime().

~BStopWatch()

      ~BStopWatch(void)

Stops the object's timer, spits out a timing message to standard out (unless it's running silently), and then destroys the object and everything it believes in. 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 was last Reset(). This function doesn't print the time message, nor does it touch the timer (the timer keeps running--unless it's paused).

A reminder: To printf() a 64-bit integer (such as bigtime_t), use "%Ld" in the format string:

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

Lap()

      bigtime_t Lap()

Records a "lap point" and returns the total elapsed time so far. When the object is destroyed, the lap point times are printed individually. 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.

The only way to get the lap times after they've been recorded is by destroying the object. If the object is silent, calling Lap() is effectively the same as calling ElapsedTime().

Name()

      const char *Name(void) const

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

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() start 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.

The Be Book, in lovely HTML, for the BeOS Preview Release.

Copyright © 1997 Be, Inc. All rights reserved.

Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.

Last modified June 30, 1997.