Component bsls_stopwatch [Package bsls]

Provide access to user, system, and wall times of current process. More...

Namespaces
namespace	bsls

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Accuracy and Precision
    • Accuracy on Windows
  • Usage Examples

Purpose:

Provide access to user, system, and wall times of current process.

Classes:

bsls::Stopwatch

accumulates user, system, wall times of current process

Description:

This component provides a class, bsls::Stopwatch, that implements real-time (system clock) interval timers for the system, user, and wall times of the current process. A bsls::Stopwatch object can accumulate the above values from multiple runs and always presents only the final total (zero if never started or reset to the initial state).

Accuracy and Precision:

A bsls::Stopwatch object returns its elapsed time intervals in seconds as double values. The precision is given by that of the bsls::TimeUtil component, and, as such, strives to be as high as possible. Monotonic behavior is platform-dependent, however, as are accuracy and useful precision. The user is advised to determine the actual performance on each platform of interest. In general, it is better to avoid stopping and restarting the stopwatch too often (e.g., inside a loop). It is better to measure the overhead of the loop separately and subtract that time from the over-all time interval.

Accuracy on Windows:

bsls::Stopwatch may be slow or inconsistent on some Windows machines. See the Accuracy and Precision section of bsls_timeutil.h.

Usage Examples:

The following snippets of code illustrate basic use of a bsls::Stopwatch object. First we create a stopwatch and note that the accumulated times are all initially 0.0:

  bsls::Stopwatch s;
  const double t0s = s.accumulatedSystemTime();  assert(0.0 == t0s);
  const double t0u = s.accumulatedUserTime();    assert(0.0 == t0u);
  const double t0w = s.accumulatedWallTime();    assert(0.0 == t0w);

Next we start the stopwatch such that it does not accumulate system or user times. Note that a stopwatch always accumulates wall time (i.e., as long as it is in the RUNNING state):

  s.start();
  const double t1s = s.accumulatedSystemTime();  assert(0.0 == t1s);
  const double t1u = s.accumulatedUserTime();    assert(0.0 == t1u);
  const double t1w = s.accumulatedWallTime();    assert(0.0 <= t1w);

Now stop the stopwatch and restart it so as to accumulate system and user times (i.e., by passing true to the start method):

  s.stop();
  const double t2s = s.accumulatedSystemTime();  assert(t1s == t2s);
  const double t2u = s.accumulatedUserTime();    assert(t1u == t2u);
  const double t2w = s.accumulatedWallTime();    assert(t1w <= t2w);

  s.start(bsls::Stopwatch::k_COLLECT_ALSO_CPU_TIMES);
  const double t3s = s.accumulatedSystemTime();  assert(t2s <= t3s);
  const double t3u = s.accumulatedUserTime();    assert(t2u <= t3u);
  const double t3w = s.accumulatedWallTime();    assert(t2w <= t3w);

Finally, we reset the stopwatch, which both puts it into the STOPPED state and resets all accumulated times back to their initial state (i.e., 0.0):

  s.reset();
  const double t4s = s.accumulatedSystemTime();  assert(0.0 == t4s);
  const double t4u = s.accumulatedUserTime();    assert(0.0 == t4u);
  const double t4w = s.accumulatedWallTime();    assert(0.0 == t4w);
  const double t5s = s.accumulatedSystemTime();  assert(0.0 == t5s);
  const double t5u = s.accumulatedUserTime();    assert(0.0 == t5u);
  const double t5w = s.accumulatedWallTime();    assert(0.0 == t5w);